Mainsail

Mainsail is a lightweight, responsive web UI designed to expose the full capabilities of Klipper firmware for 3D printers. From a developer’s standpoint, it serves as a bridge between the low‑level Klipper JSON RPC API and a modern, single‑page application (SPA) that can be deployed on any web server or containerized environment. The core goal is to keep the UI fast and modular while providing a rich set of features such as printer‑farm management, G‑code editing, and real‑time telemetry.

Technical Stack

Mainsail is built entirely with JavaScript (ES6+) and the Vue.js 3 framework. It leverages Vue Router for client‑side navigation, Pinia for state management, and Vite as the build tool. The UI communicates with Klipper via its Moonraker backend, which exposes a WebSocket‑based JSON RPC interface. All data is fetched and streamed through this channel, allowing the UI to stay in sync with printer state without polling. For persistence and configuration, Mainsail relies on the JSON files that Klipper writes to disk; no external database is required, simplifying deployment.

Core Capabilities

• Printer Farm: The UI can connect to multiple Klipper instances over WebSockets, presenting them in a unified dashboard. Developers can programmatically add or remove printers via the REST endpoints exposed by Moonraker.
• File Management & Editing: The file tree API is wrapped in a Vue component that supports drag‑and‑drop, inline editing with syntax highlighting (via CodeMirror), and bulk operations.
• Job Queue & Timelapse: Mainsail exposes a queue service that pushes jobs to Klipper’s gcode API. Timelapse integration is handled through a dedicated plugin that listens for job events and triggers moonraker-timelapse.
• Webhooks & Extensibility: Moonraker can forward printer events to external URLs. Developers can hook into these webhooks to trigger CI pipelines, send notifications, or integrate with home‑automation stacks like Home Assistant.

Deployment & Infrastructure

Because Mainsail is a static SPA, it can be served from any HTTP server (NGINX, Apache, Caddy) or embedded within a Docker container. The official Docker image (mainsail-crew/mainsail) bundles the UI with a lightweight NGINX server and exposes port 80 by default. For high‑availability printer farms, a reverse proxy with TLS termination and WebSocket support is recommended. Scaling horizontally is trivial: duplicate the container per printer or use a load‑balancer to route WebSocket connections to the correct Moonraker instance.

Integration & Extensibility

Mainsail’s plugin architecture is intentionally minimalistic; developers can fork the repository and add new Vue components that consume Moonraker APIs. The UI also supports localization via JSON locale files, making it straightforward to add new languages. For deeper integration, Moonraker’s REST endpoints can be consumed directly from custom scripts or microservices, allowing Mainsail to serve as a front‑end while offloading heavy processing elsewhere.

Developer Experience

The project’s documentation is hosted on docs.mainsail.xyz and follows a structured layout: quick‑start guides, API references, and contribution guidelines. The source code is well‑commented, and the community maintains an active Discord channel for real‑time support. Licensing under MIT ensures that developers can freely modify and redistribute the code, which is a significant advantage over proprietary 3D‑printing dashboards.

Use Cases

• Enterprise Print Farms: A single Mainsail instance can monitor dozens of printers, each running its own Klipper firmware, with centralized job queues and analytics.
• Home Automation: Integrate Mainsail with Home Assistant or Node‑RED to trigger alerts when a print completes or fails.
• Rapid Prototyping: Developers can spin up a Docker container in minutes, expose it via port forwarding, and start experimenting with custom G‑code generators or slicer integrations.

Advantages

Mainsail’s lightweight footprint (under 10 MB for the static assets), combined with its WebSocket‑based real‑time updates, delivers a snappy user experience even on low‑end hardware. Its open‑source nature and tight coupling with Klipper’s native APIs make it a preferred choice for developers who need full control over printer behavior without the overhead of proprietary dashboards. The modular architecture ensures that future features—such as advanced analytics or multi‑user support—can be added with minimal friction.