webpack-mjml-loader

2.0.1 verified Sat Apr 25 auth: no javascript

A webpack loader that compiles MJML email templates into HTML strings at build time. Current stable version is 2.0.1 (released March 2025), targeting webpack 5 exclusively. For webpack 4, use v1.1.0. MJML is a peer dependency, allowing you to choose any MJML v4+ version. Key differentiators: forwards all MJML options (like minification) via loader options, outputs HTML as a default export string, and ships TypeScript definitions. Compared to other MJML loaders, this one is simple, well-maintained, and explicitly designed for webpack 5.

Common errors

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Webpack config does not have a rule for .mjml files or the loader is not applied.

fix

Add a module rule in webpack.config.js: { test: /\.mjml$/, use: 'webpack-mjml-loader' }

error Cannot find module 'mjml' ↓

cause MJML peer dependency is not installed.

fix

Run: npm install -D mjml

error TypeScript: Cannot find module './email.mjml' or its corresponding type declarations. ↓

cause TypeScript does not recognize .mjml files without a module declaration.

fix

Create a declaration file (e.g., global.d.ts) with: declare module '*.mjml' { const content: string; export default content; }

Warnings

breaking v2.0.0 drops webpack 4 support – upgrade to webpack 5 or stay on v1.1.0. ↓

fix Use webpack 5. If you must use webpack 4, pin to webpack-mjml-loader@1.1.0.

deprecated v1.x will not receive updates – new features only for v2. ↓

fix Migrate to v2 and webpack 5.

gotcha MJML must be installed as a peer dependency – missing it causes an error at build time. ↓

fix Run: npm install -D mjml

gotcha Options are forwarded to MJML's mjml2html – misconfigured options (e.g., invalid validationLevel) can silently produce broken HTML. ↓

fix Refer to MJML documentation for valid options. Start without options and add gradually.

Install

npm install webpack-mjml-loader

yarn add webpack-mjml-loader

pnpm add webpack-mjml-loader

Imports

default import from .mjml file
wrong
```
import { template } from './email.mjml'
```
correct
```
import template from './email.mjml'
```
The loader converts MJML to an HTML string as the default export. Named import will fail.

webpack rule for .mjml files

wrong

module.exports = { module: { rules: [ { test: /\.mjml$/, loader: 'webpack-mjml-loader' } ] } }

correct

module.exports = { module: { rules: [ { test: /\.mjml$/, use: 'webpack-mjml-loader' } ] } }

Use the `use` property for loaders in webpack 5. The `loader` shorthand is deprecated.

TypeScript import
wrong
```
import * as template from './email.mjml'
```
correct
```
import template from './email.mjml'
```
TypeScript users may need to add a module declaration for .mjml files: declare module '*.mjml' { const content: string; export default content; }

Quickstart

Shows how to install, configure webpack rule for .mjml files, and import compiled HTML string.

// Install:
// npm install -D webpack-mjml-loader mjml
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.mjml$/,
        use: [
          {
            loader: 'webpack-mjml-loader',
            options: { minify: true }
          }
        ]
      }
    ]
  }
};
// email.mjml
<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text>Hello World!</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>
// app.js
import template from './email.mjml';
console.log(template); // HTML string output