ESP3D-WEBUI: a browser front end for ESP32 boards driving 3D printers and CNC

The firmware you run decides which build you make

ESP3D-WEBUI is a web interface for boards based on the ESP8266 or the ESP32 that are connected to 3D printers or CNC machines, and the repository is not a single application. It is a family of builds, one per combination of machine type and firmware, and the build scripts are named accordingly. The systems are cnc, which covers a CNC system with a laser and a spindle, printer for a 3D printer, and sand for a sand table. The firmware choices depend on the system: grbl and grblhal for the CNC side, marlin, marlin-embedded using esp3dlib, repetier and smoothieware for the printer, and grbl for the sand table. The compatibility list at the top is the constraint that matters, since the interface is only compatible with ESP3DLib 3.0, ESP3D 3.1, grblHAL and ESP3D_TFT 1.0. A board running Marlin or GRBL on its own, without the ESP3D layer in between, is outside the scope of this project.

Node and npm, then a dev server per target

Setting up the development environment is two steps. The first is the current Node.js LTS, tested with v24.14.0, and the versions in use are checked with the two version commands:

node -v
v24.14.0

npm -v
11.11.0

The second is installing the packages, run in the ESP3D-WEBUI directory at the repository root:

npm install

The dev server is then started with a script named for the system and the firmware, again from the repository root:

npm run dev-<system>-<firmware>

That script opens http://localhost:8088, which displays the web interface using a local test server. Behind the scenes each dev script sets two environment variables, a target environment and a subtarget environment, and then runs the server and the front end concurrently, so a change to the interface is picked up without a rebuild. The scripts are visible in the package manifest, and one of them sets the subtarget to grblHAL in lower case while another sets it to Marlin, so the spelling of the firmware name in the environment is not always the same as the spelling in the script name. That is a small trap when you write your own script.

Preact and spectre.css replaced Bootstrap

The front end stack is worth a paragraph because it explains the shape of the source tree. The project uses Preact, on the suggestion of a contributor, and it was rewritten to use the proper Preact API and lighter CSS code, using spectre.css instead of Bootstrap 4.x. The point of that change is size, and size matters here in a way it does not for a desktop application. The interface has to be served from a microcontroller with a small amount of RAM, and every kilobyte of JavaScript and CSS is bandwidth taken away from the machine control traffic on the same connection. The repository layout is consistent with that: a src directory for the front end code, a server directory, a config directory holding the webpack development and production configurations, a dist directory for build output, a languages directory, an extensions directory with an extensions_samples directory alongside it, and a themes_samples directory. The dist directory is committed, because the artefact that gets flashed to a board is a file, not a build.

The shipped artefact is a gzipped index.html

The production build produces one file per target, and the build command for all of them is:

npm run buildall

That generates the production version for each target and firmware into the dist directory. If you only want one, the script takes the same system and firmware pair:

npm run <system>-<firmware>

The output is an index.html.gz, a gzipped HTML file, which is the form that gets embedded in the firmware image on the ESP3D side. There is no bundle of assets to deploy and no server to run on the device, which is exactly why the compression and the Preact choice matter. A single gzipped file also means there is no runtime dependency on the machine's filesystem layout for the interface, so the same build works whether the board serves from flash or from an SD card. The webpack production configuration is what produces it, and the build scripts in the package manifest set the target and subtarget environment variables the same way the dev scripts do, which is the mechanism that lets one source tree produce a printer interface and a CNC interface with different controls.

What the project is and is not responsible for

The repository holds only the interface, and the README is explicit that it sits alongside other projects. The compatibility list names the four things it works with, and the broader information is gathered at esp3d.io rather than here. The primary language is JavaScript, and the project description in the package manifest is short: a web UI for ESP3D V3 based firmware. The project also points out the two related pieces in the family, ESP3DLib, which is the library the firmware side uses, and ESP3D_TFT, a build for the ESP3D boards with a screen. The division of labour is what keeps this project small: the firmware owns the motion control and the protocol, and the web interface owns the rendering and the input handling, and the two meet at a defined API version. When something in the interface misbehaves on hardware, the first question to ask is which side of that boundary the fault is on, and the compatibility list is the first thing to check.

A disclaimer with no warranty of any kind

The README leads with a disclaimer, and it is more than boilerplate because of what the software drives. The software is provided as is, without any warranty of any kind, expressed or implied, including the warranties of merchantability, fitness for a particular purpose and non-infringement, and in no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from the software or its use. The text asks you to read and understand it before using the software, and to refrain if you do not agree with it. Given what this project is, a web interface for the controller of a machine with a spinning spindle or a heated nozzle, that disclaimer is a sensible statement of where responsibility sits. The licence field on the repository says GPL-3.0, so the code itself is copyleft, and the contrast between a copyleft codebase and a no-warranty grant is normal and not a contradiction. Support is handled on a Discord server, and the project has a sponsors program with diamond, platinum and lower tiers.

Editorial conclusion

ESP3D-WEBUI suits someone running ESP3D on an ESP32 or ESP8266 who wants a proper browser interface for their printer or CNC machine, and who is willing to match the build script to their firmware. It does not suit someone whose board runs Marlin or GRBL directly without the ESP3D layer, because the compatibility list is explicit about what it talks to. Before you start, check the firmware and library versions, since the interface is only compatible with ESP3DLib 3.0, ESP3D 3.1, grblHAL, ESP3D_TFT 1.0, and read the disclaimer, because the software is provided as is with no warranty of any kind.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. luc-github/ESP3D-WEBUI on GitHub
4. README
5. Releases