Skip to main content

Start Here

AxioCNC is a web-based interface for CNC controllers (Grbl, Marlin, Smoothie, TinyG) built on a Node.js/Express backend with a modern React 18 + TypeScript + Vite frontend. The project prioritizes stability and predictability for long-running CNC jobs, with a focus on preventing costly mistakes through careful UI design and reliable G-code execution.

Tech Stack:

  • Backend: Node.js 18+, Express.js, Socket.IO, Winston logging
  • Frontend: React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui, Redux Toolkit
  • Desktop: Electron (bundles server + web frontend)
  • Testing: tap (Test Anything Protocol) for server tests
  • Build: pnpm workspaces monorepo, Babel (server), Vite (web)

Who This Is For​

This documentation is for open-source contributors who want to:

  • Fix bugs or add features
  • Understand the codebase architecture
  • Set up a local development environment
  • Submit pull requests

If you're an AxioCNC user looking for installation guides, usage help, or general documentation, go to axiocnc.com/docs. These dev docs are for contributors, not end users.

Project Principles​

1. Stability First​

danger

This code controls dangerous machines of people you will never meet.

Bugs can cause:

  • Machine crashes (uncontrolled movement)
  • Tool breakage
  • Workpiece damage
  • Personal injury

Protected code areas require extra care when modifying. See Making Changes Safely.

2. Easy Installation​

Customers should be able to install and run AxioCNC with minimal friction:

  • Native installers for Linux, Windows, macOS
  • Raspberry Pi packages (ARM32/ARM64)
  • Single command startup
  • Clear error messages

3. Intuitive Workflow​

The interface should:

  • Follow the workflow of most CNC jobs (setup → run → monitor)
  • Allow any workflow possible (flexible, not prescriptive)
  • Prevent accidental actions (spaced controls, confirmations)
  • Provide clear feedback (status, progress, errors)

What's Next?​

  1. Get Set Up - Install dependencies and run the app locally
  2. Repository Map - Understand the codebase structure
  3. Day-1 Workflow - Learn the development loop