Mosaico: A Template-Driven Email Editor for Web Applications

Mosaico's Template-Controlled Editing Model

Mosaico addresses a specific integration problem: building an email template editor into a web application without hard-coding every editable field into the application. It is aimed at developers who need a browser-based interface for editing HTML email templates, including applications used for newsletters, CRM communication, and agency workflows. The README identifies integrations with MailTrain and CiviCRM, although those are examples of surrounding applications rather than parts of the Mosaico distribution.

The important boundary is between the editor and the template. Mosaico does not define what users can edit or which styles they can change. The template supplies that definition. This lets an application offer different editing surfaces for different email designs without requiring every field to be implemented in the editor code. It also means that the quality and flexibility of the result depend heavily on how carefully the template author declares editable content and styling.

The repository describes Mosaico as a JavaScript library, while also calling it a single-page application. In practical terms, the repository contains the front-end editor and a development backend for serving it. The live site at mosaico.io is not a direct representation of a minimal installation: its deployment uses a custom backend and custom features, including a Moxiemanager integration for image editing, a changed onboarding slideshow, a contextual menu, and other adjustments. The README states that most of the visible demo is supplied by the open source library, but it does not document those customizations as part of the default repository.

The Editing Architecture and Its Dependencies

The repository entry point is `src/js/app.js`, and `package.json` identifies Mosaico as version `0.18.11`. The editor is built around JavaScript UI dependencies rather than a modern standalone component package. The declared dependencies include Knockout, `knockout-jqueryui`, `knockout-sortable`, `ko-reactor`, jQuery, jQuery UI, TinyMCE, Selectize, `slick`, `tinycolor2`, and other browser libraries.

The package configuration shows a Browserify-based build with `aliasify`, `browserify-shim`, and `browserify-versionify`. It also maps several dependencies to globals supplied by the hosting page, including `jQuery`, `ko`, `kojqui`, and `tinymce`. That detail matters for integration. Mosaico is not described as a self-contained component that can simply be imported into any page. The host application may need to provide compatible global libraries and load them in the expected order.

The project uses Grunt for development tasks. The README identifies a local web server at `http://127.0.0.1:9006`, with incremental building and livereload supplied by the development workflow. The repository also includes a `backend` directory, templates, resource files, task files, and tests. Those entries indicate that the editor is more than a single HTML file, although the README does not provide a complete integration API or a detailed server contract.

The template model is the editor's main extension mechanism. The README links to a Template Language wiki page and says that the open source distribution includes one production-ready template. A second template named versafluid appears in the live demo but is not included in the open source distribution. Developers who want a new design must therefore prepare the template for Mosaico rather than assuming that arbitrary email HTML will expose the expected editing controls.

Building Mosaico with NodeJS and Grunt

The README specifies NodeJS v24.0 or higher and NPM 8.3. NPM 8.3 is needed if you want to change or upgrade dependencies because the project uses `overrides` in `package.json`. The README says older npm versions may work when relying on `package-lock.json`. The first step is to install the project dependencies from the repository root. The command below is the exact command documented by the project.

npm install

The README warns that the installation may need to be run again if an error occurs, describing the problem as a possible npm race issue. After installation, the documented build tool is `grunt`. If the command is not available, the project documents a global `grunt-cli` installation.

npm install -g grunt-cli

The local development command starts the documented build and server workflow.

grunt

A successful run should make the development site available at `http://127.0.0.1:9006`. The command also provides the incremental build and livereload behavior described in the README. A Ubuntu installation may encounter `Fatal error: watch ENOSPC`; the README directs users to issue 82 for that specific failure rather than presenting it as a general Mosaico configuration error.

Running the Editor Through the Included Docker Setup

For a container-based local setup, the repository includes a Dockerfile based on Alpine Linux. The README gives two commands, first building an image and then publishing the container on port 9006.

docker build -t mosaico/mosaico .

After the image is built, start it with the documented port mapping.

docker run -p 9006:9006 mosaico/mosaico

The expected result is a running service on port 9006. The README instructs the reader to open a browser to port 9006 of the Docker machine IP. The included Dockerfile uses `node:18-alpine`, installs build utilities and `grunt-cli`, copies the package files, installs dependencies, copies the repository, exposes port 9006, and runs `grunt default`.

This container path is convenient for evaluating the repository without installing the dependencies directly on the host. It does not make the live demo's private backend public. The README explicitly separates the custom backend and demo customizations from the open source library. A production deployment also requires building Mosaico and reading the Serving Mosaico guidance before putting it behind Apache PHP, Django, or another server.

Where Mosaico Falls Short as a Complete Email Platform

Mosaico is an editor library, not a complete email marketing application. The repository does not present campaign sending, subscriber management, delivery infrastructure, analytics, or mailing-list workflows as features of Mosaico itself. The live demo uses a custom backend, and the README names separate projects such as MailTrain and GoodEnough's Mosaico as applications built around or related to Mosaico. That distinction makes Mosaico the wrong tool when the requirement is an out-of-the-box newsletter service.

The template dependency is also a constraint. Because templates define what can be edited and which styles are available, an incompatible template may not produce the controls an application expects. The repository says that the open source distribution provides one production-ready template, while versafluid is available only through the live demo. Teams cannot infer from the editor library alone that every template in the hosted demo is available under the same distribution terms.

The documented backend behavior is limited. The README points to a Serving Mosaico wiki page for Apache PHP, Django, and other deployments, but it does not provide a short API contract for saving templates, handling uploads, managing authentication, or replacing the demo's custom features. Mosaico may be a suitable editor component for a larger product, but the larger product owns those responsibilities.

Mosaico Compared with Application-Level Email Editors

MailTrain is listed as an open source newsletter web application that supports email editing through Mosaico from version 1.23.0. Its approach is application-level: the product supplies a newsletter system around the editor rather than asking the adopter to build subscriber and campaign workflows from the editor alone. That is the clearest alternative described in the README.

The difference is scope. Mosaico gives developers the browser editing surface and a template-defined model. MailTrain adds a full featured newsletter application around it. GoodEnough's Mosaico is described as a fork that became a full web application product aimed at agencies. Its existence shows another path: build a product around Mosaico rather than deploying the library unchanged.

For a team that only needs a reusable email editor, choosing MailTrain could add application responsibilities the team does not need. For a team that needs subscriber management and newsletter workflows, Mosaico alone leaves those pieces outside the project. The choice should follow the required product boundary, not a claim that one editor produces better HTML.

Mosaico Maintenance, Licensing, and Upgrade Work

The repository is not archived, and the last push was on 2026-09-22. The release history lists v0.18.11 on 2025-08-22, v0.18.10 on 2023-07-04, and v0.18.9 on 2022-11-10. These dates show that the most recent listed release predates the last repository push, so the default branch may contain work beyond the latest named release. They do not establish how frequently future releases will be published.

The project is licensed under GPL-3.0. That identifier affects how a distributor handles the licensed code, but this review does not provide legal interpretation. Organizations should review the repository's `LICENSE` and `NOTICE.txt` files for the actual obligations relevant to their deployment and distribution model.

An upgrade can also involve more than changing a version number. The package uses a lockfile, global browser dependencies, Grunt tasks, template language files, and a server integration. The README's dependency override note means that changing dependencies may require NPM 8.3 or newer. Before changing the editor stack, check the lockfile and the Serving Mosaico documentation rather than treating `package.json` as an isolated application dependency.

Editorial conclusion

Adopt Mosaico when an application needs a browser editor whose editable fields and available styles are defined by the email template itself. Do not choose it as a standalone email campaign service or assume that its live demo backend is included. Verify first whether your own server can serve the built editor, whether your template follows the Template Language, and how image uploads, image editing, onboarding, contextual menus, and other demo customizations will be replaced or implemented.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. voidlabs/mosaico on GitHub