@emailens/cli 0.13.1 → 0.13.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,186 +1,188 @@
1
- <div align="center">
2
-
3
- <picture>
4
- <source media="(prefers-color-scheme: dark)" srcset="./docs/wordmark-dark.svg">
5
- <img src="./docs/wordmark-light.svg" alt="emailens / cli" width="444">
6
- </picture>
7
-
8
- **The email rendering linter for terminal and CI**
9
-
10
- [![CI](https://github.com/emailens/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/emailens/cli/actions/workflows/ci.yml)
11
- [![npm](https://badgen.net/npm/v/@emailens/cli)](https://www.npmjs.com/package/@emailens/cli)
12
- [![MCP](https://badgen.net/badge/MCP/Server/blue)](https://github.com/emailens/mcp)
13
-
14
- </div>
15
-
16
- ```text
17
- $ emailens lint emails/welcome.html --fail-on-warning
18
- emails/welcome.html
19
- warn 6:17 outlook-windows-legacy display:flex Outlook Classic receives this flex box. The MSO branch needs a table.
20
- warn 6:30 outlook-windows-legacy,yahoo-mail,yahoo-mail-android+2 gap Outlook Classic does not support "gap".
21
- warn 6:39 outlook-windows-legacy,outlook-windows-legacy padding Outlook Classic drops this padding. Put it on a table cell, or set mso-padding-alt on one.
22
- warn inboxPreview preheader-too-short Preheader is only 22 characters, so email clients may backfill with body text (recommended: 30+).
23
- 9 info: safe fallbacks, not problems. --info lists them.
24
-
25
- 1 file | 4 warnings
26
-
27
- Failed: 4 warnings found (--failOnWarning)
28
- See it rendered in Gmail, Outlook and Apple Mail, no signup: https://app.emailens.dev/try?utm_source=cli&utm_medium=lint
29
- ```
30
-
31
- That is a flex row with a rounded button, checked against 21 email clients.
32
- Each finding has its line:column, and the exit code (here 2) fails the build.
33
- The rounded corners are among the 9 info findings: Outlook Classic draws them
34
- square, a safe fallback rather than a problem. The last line appears only when
35
- the check fails; `--quiet` drops it, and `--json` never has it.
36
-
37
- ## Install
38
-
39
- ```bash
40
- npm install -g @emailens/cli
41
- ```
42
-
43
- ## Run
44
-
45
- ```bash
46
- emailens lint 'emails/*.html'
47
- ```
48
-
49
- Or without installing: `npx @emailens/cli lint email.html`. HTML, React Email
50
- (`.tsx`/`.jsx`), MJML and Maizzle are detected from the extension and compiled
51
- first, so the check runs on the HTML that would be sent. No account and no
52
- network: the analysis runs locally.
53
-
54
- Exit codes: `0` clean, `1` errors, `2` warnings with `--fail-on-warning`, or
55
- more than `--max-warnings`.
56
-
57
- ## Why not caniemail, or React Email's own checker?
58
-
59
- [Can I email](https://www.caniemail.com) is the support table: one feature,
60
- every client. It does not read your email. This CLI's support data is generated
61
- from caniemail's (synced 2026-10-27), plus the cells a real-device screenshot
62
- contradicted, each marked "Observed" with its date. What the CLI adds is the
63
- reading: it finds the features your file uses, points at the line, scores each
64
- client, and exits non-zero.
65
-
66
- [React Email 4](https://resend.com/blog/react-email-4) added a compatibility
67
- checker, also powered by Can I email, to its preview. Its CLI (`email dev`,
68
- `build`, `start`, `export`) has no check command and no exit code for CI, per
69
- [its docs](https://react.email/docs/cli). This CLI reads React Email files as
70
- well as MJML, Maizzle and plain HTML, and fails the build.
71
-
72
- Beyond CSS support, `lint` checks what neither covers: spam signals, links,
73
- accessibility, images, the inbox preview text, size, template variables,
74
- overflow, dark-mode and mobile contrast, Outlook VML, styles a client drops, and
75
- client-targeting hacks.
76
-
77
- ## Extras
78
-
79
- ### `lint` options
80
-
81
- | Flag | Alias | Description |
82
- |------|-------|-------------|
83
- | `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle`. `.vue` is `maizzle`. A pasted Vue file with no flag is detected. |
84
- | `--json` | | Output as JSON, one line, every finding including info |
85
- | `--info` | | List info findings too. By default they are counted, not listed: they are safe fallbacks, not problems |
86
- | `--fail-on-warning` | | Exit 2 if warnings found |
87
- | `--max-warnings` | | Fail if more than n warnings |
88
- | `--reporter github` | | Also print GitHub Actions annotations, so each finding shows on its line in the pull request. Not with `--json` |
89
- | `--quiet` | `-q` | No line about the hosted preview after a failure |
90
- | `--skip` | | Comma-separated checks to skip: `spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables,overflow,visual,darkContrast,mobileContrast,design,vml,styleSurvival,targeting` |
91
- | `--targeting-policy` | | `progressive` (default), `strict`, or `lenient` |
92
-
93
- A `.emailensrc` in the project, the file the VS Code extension reads, can set
94
- rule severities and skips; `--skip` on the command line wins.
95
-
96
- Maizzle HTML needs `@maizzle/framework@5` installed beside the CLI. A `.vue`
97
- file needs `@maizzle/framework@6`. One install is one major.
98
-
99
- ### Other commands
100
-
101
- ```bash
102
- emailens analyze email.html # score per client, findings by client
103
- emailens analyze email.html --clients gmail-web,outlook-windows --json
104
- emailens audit email.html # compatibility plus every other check
105
- emailens preview email.html --dark-mode # transforms, analysis, dark mode simulation
106
- emailens preview email.html --screenshots --out ./shots # needs BROWSERLESS_URL and playwright-core
107
- emailens export email.html -o ./report # self-contained HTML report (--json for JSON)
108
- emailens fix email.html -o fixed.html # AI fix, needs ANTHROPIC_API_KEY (--estimate: tokens only)
109
- emailens clients # the 21 clients
110
- cat email.html | emailens analyze - # stdin
111
- ```
112
-
113
- ### `emailens inbox wait`
114
-
115
- The CI step for what your app actually sends. Make your app send a real email
116
- (sign-up, reset, receipt) to your Emailens test inbox, then wait for it. It
117
- fails when the email is no longer the one you checked in Emailens, or changed
118
- since it last arrived: a link moved to staging, an emptied variable, a new
119
- line, an image gone, a size jump, signing that stopped passing. Codes, tokens
120
- and tracking ids differ on every send and do not count. It needs an API key.
121
-
122
- ```bash
123
- export EMAILENS_API_KEY=... # app.emailens.dev/dashboard/api
124
- SINCE=$(date +%s000) # before the send
125
- npm run send-signup-email # your app sends it
126
- emailens inbox wait --subject "Welcome" --since "$SINCE"
127
- ```
128
-
129
- Options: `--subject`, `--sender`, `--inbox <id>`, `--since` (ISO time, epoch
130
- ms, or a duration such as `5m`; default 2 minutes back), `--timeout` (seconds,
131
- default 60, at most 600), `--fail-on all|check|drift|none` (default `all`),
132
- `--json`. Exit codes: `0` pass, `1` changed, `2` nothing arrived or Emailens
133
- could not be reached.
134
-
135
- ### In your tests
136
-
137
- The same check as `lint`, as an assertion. It throws with every failing
138
- finding and its line, reads your `.emailensrc`, and works in Vitest, Jest and
139
- bun:test.
140
-
141
- ```ts
142
- import { render } from "@react-email/render";
143
- import { expectEmailToPass } from "@emailens/cli/test";
144
-
145
- test("welcome email passes", async () => {
146
- expectEmailToPass(await render(<Welcome name="Ada" />));
147
- });
148
- ```
149
-
150
- Options: `failOnWarning`, `skip` (the `--skip` names), `framework`.
151
-
152
- ### In GitHub Actions
153
-
154
- ```yaml
155
- - uses: actions/setup-node@v4
156
- with:
157
- node-version: 22
158
- - run: npx -y @emailens/cli lint 'emails/*.html' --fail-on-warning --reporter github
159
- ```
160
-
161
- `--reporter github` puts each finding on its line in the pull request's
162
- changed files.
163
-
164
- `**` globs are not supported: use a single-level wildcard or list the files.
165
- For scores per client in a pull request comment, use the
166
- [Action](https://github.com/emailens/action).
167
-
168
- ### Hosted
169
-
170
- [app.emailens.dev/try](https://app.emailens.dev/try?utm_source=cli&utm_medium=readme)
171
- renders the email per client: five clients with no account, all 21 with a free
172
- one. The + Real plans add real-device screenshots: Outlook on Windows and Mac,
173
- Apple Mail on Mac and iPad, and Gmail, Yahoo and Proton on the web.
174
-
175
- ## Ecosystem
176
-
177
- | Project | What it is |
178
- |---|---|
179
- | [@emailens/engine](https://github.com/emailens/engine) | The analysis engine this CLI runs, as a library |
180
- | [@emailens/mcp](https://github.com/emailens/mcp) | The same checks for coding agents: `claude mcp add emailens -- npx -y @emailens/mcp` |
181
- | [emailens/action](https://github.com/emailens/action) | GitHub Action: fails the build, and can comment the scores per client on the pull request |
182
- | [emailens/vscode](https://github.com/emailens/vscode) | VS Code extension: findings and preview in the editor |
183
-
184
- ## License
185
-
186
- MIT
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="./docs/wordmark-dark.svg">
5
+ <img src="./docs/wordmark-light.svg" alt="emailens / cli" width="444">
6
+ </picture>
7
+
8
+ **The email rendering linter for terminal and CI**
9
+
10
+ [![CI](https://github.com/emailens/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/emailens/cli/actions/workflows/ci.yml)
11
+ [![npm](https://badgen.net/npm/v/@emailens/cli)](https://www.npmjs.com/package/@emailens/cli)
12
+ [![MCP](https://badgen.net/badge/MCP/Server/blue)](https://github.com/emailens/mcp)
13
+
14
+ </div>
15
+
16
+ ```text
17
+ $ emailens lint emails/welcome.html --fail-on-warning
18
+ emails/welcome.html
19
+ warn 7:10 outlook-windows-legacy display:flex Outlook Classic receives this flex box. The MSO branch needs a table.
20
+ warn 7:25 outlook-windows-legacy,yahoo-mail,yahoo-mail-android+2 gap Outlook Classic does not support "gap".
21
+ warn 8:32 gmail-web,outlook-windows-legacy,yahoo-mail-android+2 box-shadow Gmail does not support "box-shadow".
22
+ warn 14:5 yahoo-mail font-family Yahoo Mail drops an inline font-family that names a quoted font, like 'Courier New': that text shows in Yahoo's own font instead.
23
+ warn inboxPreview preheader-too-short Preheader is only 21 characters, so email clients may backfill with body text (recommended: 30+).
24
+ 12 info: safe fallbacks, not problems. --info lists them.
25
+
26
+ 1 file | 5 warnings
27
+
28
+ Failed: 5 warnings found (--failOnWarning)
29
+ See it rendered in Gmail, Outlook and Apple Mail, no signup: https://app.emailens.dev/try?utm_source=cli&utm_medium=lint
30
+ ```
31
+
32
+ That is a welcome email with a flex row and a card shadow, checked against 21
33
+ email clients. Each finding has its line:column, and the exit code (here 2)
34
+ fails the build. The card's rounded corners are among the 12 info findings:
35
+ Outlook Classic draws them square, a safe fallback rather than a problem. The
36
+ last line appears only when the check fails; `--quiet` drops it, and `--json`
37
+ never has it.
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ npm install -g @emailens/cli
43
+ ```
44
+
45
+ ## Run
46
+
47
+ ```bash
48
+ emailens lint 'emails/*.html'
49
+ ```
50
+
51
+ Or without installing: `npx @emailens/cli lint email.html`. HTML, React Email
52
+ (`.tsx`/`.jsx`), MJML and Maizzle are detected from the extension and compiled
53
+ first, so the check runs on the HTML that would be sent. No account and no
54
+ network: the analysis runs locally.
55
+
56
+ Exit codes: `0` clean, `1` errors, `2` warnings with `--fail-on-warning`, or
57
+ more than `--max-warnings`.
58
+
59
+ ## Why not caniemail, or React Email's own checker?
60
+
61
+ [Can I email](https://www.caniemail.com) is the support table: one feature,
62
+ every client. It does not read your email. This CLI's support data is generated
63
+ from caniemail's (synced 2026-10-27), plus the cells a real-device screenshot
64
+ contradicted, each marked "Observed" with its date. What the CLI adds is the
65
+ reading: it finds the features your file uses, points at the line, scores each
66
+ client, and exits non-zero.
67
+
68
+ [React Email 4](https://resend.com/blog/react-email-4) added a compatibility
69
+ checker, also powered by Can I email, to its preview. Its CLI (`email dev`,
70
+ `build`, `start`, `export`) has no check command and no exit code for CI, per
71
+ [its docs](https://react.email/docs/cli). This CLI reads React Email files as
72
+ well as MJML, Maizzle and plain HTML, and fails the build.
73
+
74
+ Beyond CSS support, `lint` checks what neither covers: spam signals, links,
75
+ accessibility, images, the inbox preview text, size, template variables,
76
+ overflow, dark-mode and mobile contrast, Outlook VML, styles a client drops, and
77
+ client-targeting hacks.
78
+
79
+ ## Extras
80
+
81
+ ### `lint` options
82
+
83
+ | Flag | Alias | Description |
84
+ |------|-------|-------------|
85
+ | `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle`. `.vue` is `maizzle`. A pasted Vue file with no flag is detected. |
86
+ | `--json` | | Output as JSON, one line, every finding including info |
87
+ | `--info` | | List info findings too. By default they are counted, not listed: they are safe fallbacks, not problems |
88
+ | `--fail-on-warning` | | Exit 2 if warnings found |
89
+ | `--max-warnings` | | Fail if more than n warnings |
90
+ | `--reporter github` | | Also print GitHub Actions annotations, so each finding shows on its line in the pull request. Not with `--json` |
91
+ | `--quiet` | `-q` | No line about the hosted preview after a failure |
92
+ | `--skip` | | Comma-separated checks to skip: `spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables,overflow,visual,darkContrast,mobileContrast,design,vml,styleSurvival,targeting` |
93
+ | `--targeting-policy` | | `progressive` (default), `strict`, or `lenient` |
94
+
95
+ A `.emailensrc` in the project, the file the VS Code extension reads, can set
96
+ rule severities and skips; `--skip` on the command line wins.
97
+
98
+ Maizzle HTML needs `@maizzle/framework@5` installed beside the CLI. A `.vue`
99
+ file needs `@maizzle/framework@6`. One install is one major.
100
+
101
+ ### Other commands
102
+
103
+ ```bash
104
+ emailens analyze email.html # score per client, findings by client
105
+ emailens analyze email.html --clients gmail-web,outlook-windows --json
106
+ emailens audit email.html # compatibility plus every other check
107
+ emailens preview email.html --dark-mode # transforms, analysis, dark mode simulation
108
+ emailens preview email.html --screenshots --out ./shots # needs BROWSERLESS_URL and playwright-core
109
+ emailens export email.html -o ./report # self-contained HTML report (--json for JSON)
110
+ emailens fix email.html -o fixed.html # AI fix, needs ANTHROPIC_API_KEY (--estimate: tokens only)
111
+ emailens clients # the 21 clients
112
+ cat email.html | emailens analyze - # stdin
113
+ ```
114
+
115
+ ### `emailens inbox wait`
116
+
117
+ The CI step for what your app actually sends. Make your app send a real email
118
+ (sign-up, reset, receipt) to your Emailens test inbox, then wait for it. It
119
+ fails when the email is no longer the one you checked in Emailens, or changed
120
+ since it last arrived: a link moved to staging, an emptied variable, a new
121
+ line, an image gone, a size jump, signing that stopped passing. Codes, tokens
122
+ and tracking ids differ on every send and do not count. It needs an API key.
123
+
124
+ ```bash
125
+ export EMAILENS_API_KEY=... # app.emailens.dev/dashboard/api
126
+ SINCE=$(date +%s000) # before the send
127
+ npm run send-signup-email # your app sends it
128
+ emailens inbox wait --subject "Welcome" --since "$SINCE"
129
+ ```
130
+
131
+ Options: `--subject`, `--sender`, `--inbox <id>`, `--since` (ISO time, epoch
132
+ ms, or a duration such as `5m`; default 2 minutes back), `--timeout` (seconds,
133
+ default 60, at most 600), `--fail-on all|check|drift|none` (default `all`),
134
+ `--json`. Exit codes: `0` pass, `1` changed, `2` nothing arrived or Emailens
135
+ could not be reached.
136
+
137
+ ### In your tests
138
+
139
+ The same check as `lint`, as an assertion. It throws with every failing
140
+ finding and its line, reads your `.emailensrc`, and works in Vitest, Jest and
141
+ bun:test.
142
+
143
+ ```ts
144
+ import { render } from "@react-email/render";
145
+ import { expectEmailToPass } from "@emailens/cli/test";
146
+
147
+ test("welcome email passes", async () => {
148
+ expectEmailToPass(await render(<Welcome name="Ada" />));
149
+ });
150
+ ```
151
+
152
+ Options: `failOnWarning`, `skip` (the `--skip` names), `framework`.
153
+
154
+ ### In GitHub Actions
155
+
156
+ ```yaml
157
+ - uses: actions/setup-node@v4
158
+ with:
159
+ node-version: 22
160
+ - run: npx -y @emailens/cli lint 'emails/*.html' --fail-on-warning --reporter github
161
+ ```
162
+
163
+ `--reporter github` puts each finding on its line in the pull request's
164
+ changed files.
165
+
166
+ `**` globs are not supported: use a single-level wildcard or list the files.
167
+ For scores per client in a pull request comment, use the
168
+ [Action](https://github.com/emailens/action).
169
+
170
+ ### Hosted
171
+
172
+ [app.emailens.dev/try](https://app.emailens.dev/try?utm_source=cli&utm_medium=readme)
173
+ renders the email per client: five clients with no account, all 21 with a free
174
+ one. The + Real plans add real-device screenshots: Outlook on Windows and Mac,
175
+ Apple Mail on Mac and iPad, and Gmail, Yahoo and Proton on the web.
176
+
177
+ ## Ecosystem
178
+
179
+ | Project | What it is |
180
+ |---|---|
181
+ | [@emailens/engine](https://github.com/emailens/engine) | The analysis engine this CLI runs, as a library |
182
+ | [@emailens/mcp](https://github.com/emailens/mcp) | The same checks for coding agents: `claude mcp add emailens -- npx -y @emailens/mcp` |
183
+ | [emailens/action](https://github.com/emailens/action) | GitHub Action: fails the build, and can comment the scores per client on the pull request |
184
+ | [emailens/vscode](https://github.com/emailens/vscode) | VS Code extension: findings and preview in the editor |
185
+
186
+ ## License
187
+
188
+ MIT
@@ -0,0 +1,65 @@
1
+ import { createRequire as __cr } from "node:module";
2
+ const require = __cr(import.meta.url);
3
+ import {
4
+ CompileError
5
+ } from "./chunk-TQGPCAMW.js";
6
+
7
+ // node_modules/@emailens/engine/dist/chunk-E4QE4WXE.js
8
+ var MAX_SOURCE_SIZE = 512e3;
9
+ async function compileMjml(source) {
10
+ var _a;
11
+ if (!source || !source.trim()) {
12
+ throw new CompileError("MJML source must not be empty.", "mjml", "validation");
13
+ }
14
+ if (source.length > MAX_SOURCE_SIZE) {
15
+ throw new CompileError(
16
+ `MJML source exceeds ${MAX_SOURCE_SIZE / 1e3}KB limit.`,
17
+ "mjml",
18
+ "validation"
19
+ );
20
+ }
21
+ if (!/<mjml[\s>]/i.test(source)) {
22
+ throw new CompileError(
23
+ "MJML source must contain a root <mjml> element. Example: <mjml><mj-body><mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section></mj-body></mjml>",
24
+ "mjml",
25
+ "validation"
26
+ );
27
+ }
28
+ let mjml2html;
29
+ try {
30
+ const mjmlModule = await import("mjml");
31
+ mjml2html = (_a = mjmlModule.default) != null ? _a : mjmlModule;
32
+ } catch (e) {
33
+ throw new CompileError(
34
+ 'MJML compilation requires "mjml". Install it:\n npm install mjml',
35
+ "mjml",
36
+ "compile"
37
+ );
38
+ }
39
+ try {
40
+ const result = await mjml2html(source, {
41
+ validationLevel: "soft",
42
+ keepComments: false
43
+ });
44
+ if (result.errors && result.errors.length > 0 && !result.html) {
45
+ const errorMessages = result.errors.map((e) => `Line ${e.line}: ${e.message} (${e.tagName})`).join("; ");
46
+ throw new CompileError(
47
+ `MJML compilation errors: ${errorMessages}`,
48
+ "mjml",
49
+ "compile"
50
+ );
51
+ }
52
+ if (!result.html) {
53
+ throw new CompileError("MJML compilation produced empty output.", "mjml", "compile");
54
+ }
55
+ return result.html;
56
+ } catch (err) {
57
+ if (err instanceof CompileError) throw err;
58
+ const message = err instanceof Error ? err.message : "Unknown MJML compilation error";
59
+ throw new CompileError(`MJML compilation failed: ${message}`, "mjml", "compile");
60
+ }
61
+ }
62
+
63
+ export {
64
+ compileMjml
65
+ };