JavaScript CSS Other
Failed to load latest commit information.
.github Update Aug 23, 2017
bin feat: add support to listen on specific address and port by passing c… Nov 19, 2017
electron-build Build process enhancements Nov 4, 2017
examples Update .cncrc May 23, 2017
media Added Events Screenshot for documentation link Feb 18, 2018
scripts Update Jul 6, 2018
src Improve rendering performance by reducing redundant vertices from the… Jul 21, 2018
static Update instructions for serving static files with a mount point Feb 12, 2017
test Preliminary support for Marlin 3D printer firmware Nov 8, 2017
.babelrc Replace babel-preset-<year> with babel-preset-env Oct 29, 2017
.bowerrc Initial commit Sep 15, 2015
.cncrc.default Add .cncrc.default Dec 10, 2016
.eslintignore Remove non-exist directories from .eslintignore May 23, 2016
.eslintrc eslint fixes Dec 24, 2017
.gitignore Update .gitignore Jun 10, 2017
.npmignore Add /releases May 4, 2016
.stylintrc Update .stylintrc Nov 8, 2017
.travis.yml Drop support for Node.js v4 Jul 5, 2018 Update Dec 27, 2016 Build process enhancements Nov 4, 2017
Dockerfile Support for Node.js v6 Dec 25, 2017
LICENSE Update LICENSE May 14, 2017 Update Jul 20, 2018
appveyor.yml Update appveyor.yml Feb 4, 2018
build.config.js Turkish (Türkçe) language support Jan 2, 2018
i18next-scanner.appconfig.js Parsing translation strings with i18next-scanner CLI script Dec 9, 2017
i18next-scanner.webconfig.js Parsing translation strings with i18next-scanner CLI script Dec 9, 2017
package.json deps: electron@~2.0.3, serialport@~6.2.1 (#352) Jul 5, 2018
webpack.appconfig.development.js Change devtools to 'cheap-module-eval-source-map' for development and… Dec 2, 2017
webpack.appconfig.production.js Change devtools to 'cheap-module-eval-source-map' for development and… Dec 2, 2017
webpack.webconfig.base.js Resolve modules from the "src" directory Dec 4, 2017
webpack.webconfig.development.js Ordering import statements Jan 28, 2018
webpack.webconfig.production.js Ordering import statements Jan 28, 2018

CNCjs Travis CI Build Status AppVeyor Build status Coverage Status

NPM cncjs

CNCjs is a full-featured web-based interface for CNC controllers running Grbl, Marlin, Smoothieware, or TinyG.

For a more complete introduction, see the Introduction section of the wiki page.



Custom Widgets


Boilerplate Code

Existing Pendants

Tablet UI

Browser Support

Yes Yes Yes Not supported Yes Yes

Supported Node.js Versions

Version Supported Level
4 Dropped support
6 Recommended for production use
8 Recommended for production use
9 Supported
10 Supported

Getting Started

Node.js Installation

Node.js 6 or higher is recommended. You can install Node Version Manager to manage multiple Node.js versions. If you have git installed, just clone the nvm repo, and check out the latest version:

git clone ~/.nvm
cd ~/.nvm
git checkout `git describe --abbrev=0 --tags`
cd ..
. ~/.nvm/

Add these lines to your ~/.bash_profile, ~/.bashrc, or ~/.profile file to have it automatically sourced upon login:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/" ] && . "$NVM_DIR/" # This loads nvm

Once installed, you can select Node.js versions with:

nvm install 6
nvm use 6

It's also recommended that you upgrade npm to the latest version. To upgrade, run:

npm install npm@latest -g


Install cncjs as a non-root user, or the serialport module may not install correctly on some platforms like Raspberry Pi.

npm install -g cncjs

If you're going to use sudo or root to install cncjs, you need to specify the --unsafe-perm option to run npm as the root account.

sudo npm install --unsafe-perm -g cncjs

Check out for other installation methods.


Run npm install -g cncjs@latest to install the latest version. To determine the version, use cncjs -V.


Run cncjs to start the server, and visit http://yourhostname:8000/ to view the web interface. Pass --help to cncjs for more options.

pi@rpi3$ cncjs -h

  Usage: cncjs [options]


    -V, --version                       output the version number
    -p, --port <port>                   Set listen port (default: 8000)
    -H, --host <host>                   Set listen address or hostname (default:
    -b, --backlog <backlog>             Set listen backlog (default: 511)
    -c, --config <filename>             Set config file (default: ~/.cncrc)
    -v, --verbose                       Increase the verbosity level (-v, -vv, -vvv)
    -m, --mount <route-path>:<target>   Add a mount point for serving static files
    -w, --watch-directory <path>        Watch a directory for changes
    --access-token-lifetime <lifetime>  Access token lifetime in seconds or a time span string (default: 30d)
    --allow-remote-access               Allow remote access to the server (default: false)
    --controller <type>                 Specify CNC controller: Grbl|Marlin|Smoothie|TinyG|g2core (default: '')
    -h, --help                          output usage information


    $ cncjs -vv
    $ cncjs --mount /pendant:/home/pi/tinyweb
    $ cncjs --mount /widget:~+/widget --mount /pendant:~/pendant
    $ cncjs --mount /widget:
    $ cncjs --watch-directory /home/pi/watch
    $ cncjs --access-token-lifetime 60d  # e.g. 3600, 30m, 12h, 30d
    $ cncjs --allow-remote-access
    $ cncjs --controller Grbl

Instead of passing command line options for --watch-directory, --access-token-lifetime, --allow-remote-access, and --controller, you can create a ~/.cncrc file that contains the following configuration in JSON format:

    "watchDirectory": "/path/to/dir",
    "accessTokenLifetime": "30d",
    "allowRemoteAccess": false,
    "controller": ""

To troubleshoot issues, run:

cncjs -vvv

Configuration File

The configuration file .cncrc contains settings that are equivalent to the cncjs command-line options. The configuration file is stored in user's home directory. To find out the actual location of the home directory, do the following:

  • Linux/Mac

    echo $HOME
  • Windows

    echo %USERPROFILE%

Check out an example configuration file here.

File Format

See for a detailed explanation.

  "ports": [
       "comName": "/dev/ttyAMA0",
       "manufacturer": ""
  "baudrates": [115200, 250000],
  "watchDirectory": "/path/to/dir",
  "accessTokenLifetime": "30d",
  "allowRemoteAccess": false,
  "controller": "",
  "state": {
    "checkForUpdates": true,
    "controller": {
      "exception": {
        "ignoreErrors": false
  "commands": [
      "title": "Update (root user)",
      "commands": "sudo npm install -g cncjs@latest --unsafe-perm; pkill -a -f cncjs"
      "title": "Update (non-root user)",
      "commands": "npm install -g cncjs@latest; pkill -a -f cncjs"
      "title": "Reboot",
      "commands": "sudo /sbin/reboot"
      "title": "Shutdown",
      "commands": "sudo /sbin/shutdown"
  "events": [],
  "macros": [],
  "users": []



There are several *.gcode files in the examples directory. You can use the GCode widget to load a GCode file and make a trial run.

If you don't have a CAM software, try using jscut to create G-Code from *.svg. It's a simple CAM package that runs in the browser.

Check out a live demo at


Use GitHub issues for requests.

Pull requests welcome! Learn how to contribute.


You can help translate resource files in both of app and web directories from English to other languages. Check out Localization guide to learn how to get started. If you are not familiar with GitHub development, you can open an issue or send your translations to

Locale Language Status Contributors
cs Čeština (Czech) Miroslav Zuzelka
de Deutsch (German) Thorsten Godau, Max B.
es Español (Spanish) Juan Biondi
fr Français (French) Simon Maillard, CorentinBrulé
hu Magyar (Hungarian) Sipos Péter
it Italiano (Italian) vince87
ja 日本語 (Japanese) Naoki Okamoto
nl Nederlands (Netherlands) dutchpatriot
pt-br Português (Brasil) cmsteinBR
ru Ру́сский (Russian) Denis Yusupov
tr Türkçe (Turkish) Ali GÜNDOĞDU
zh-cn 简体中文 (Simplified Chinese) Mandy Chien, Terry Lee
zh-tw 繁體中文 (Traditional Chinese) Cheton Wu


If you would like to support this project, you can make a donation using PayPal. Thank you!



Licensed under the MIT License.