@emailens/cli 0.13.16 → 0.13.19
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 +207 -188
- package/dist/{chunk-FFVMVESX.js → chunk-J4YQYM4C.js} +703 -226
- package/dist/{chunk-ABDTBRVK.js → chunk-UN26YQF6.js} +6 -5
- package/dist/index.js +483 -156
- package/dist/{react-email-4EWH2SB4-CUKHMPBB.js → react-email-QQA75STN-LT3O7SQP.js} +1 -1
- package/dist/test.js +2 -2
- package/package.json +6 -2
package/README.md
CHANGED
|
@@ -1,188 +1,207 @@
|
|
|
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
|
-
[](https://github.com/emailens/cli/actions/workflows/ci.yml)
|
|
11
|
-
[](https://www.npmjs.com/package/@emailens/cli)
|
|
12
|
-
[](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
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
emailens
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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
|
+
[](https://github.com/emailens/cli/actions/workflows/ci.yml)
|
|
11
|
+
[](https://www.npmjs.com/package/@emailens/cli)
|
|
12
|
+
[](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
|
+
### In a React Email project
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npx @emailens/cli react-email
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Finds the emails folder `email dev` uses (`emails/`, `src/emails/`), renders
|
|
66
|
+
every template with your project's own React Email, `PreviewProps` included,
|
|
67
|
+
and checks the HTML. Local imports, any npm package and tsconfig paths work,
|
|
68
|
+
subfolders are included, and `_components`-style folders and files without a
|
|
69
|
+
default export are skipped. No export step. `--watch` re-checks on save.
|
|
70
|
+
|
|
71
|
+
Pass `--email-type transactional` (or set `"emailType": "transactional"` in
|
|
72
|
+
`.emailensrc`) when the folder holds sign-in, receipt and alert emails, which
|
|
73
|
+
need no unsubscribe link. `emailens lint emails/` does the same as the command
|
|
74
|
+
above on a folder you name.
|
|
75
|
+
|
|
76
|
+
## Why not caniemail, or React Email's own checker?
|
|
77
|
+
|
|
78
|
+
[Can I email](https://www.caniemail.com) is the support table: one feature,
|
|
79
|
+
every client. It does not read your email. This CLI's support data is generated
|
|
80
|
+
from caniemail's (synced 2026-10-27), plus the cells a real-device screenshot
|
|
81
|
+
contradicted, each marked "Observed" with its date. What the CLI adds is the
|
|
82
|
+
reading: it finds the features your file uses, points at the line, scores each
|
|
83
|
+
client, and exits non-zero.
|
|
84
|
+
|
|
85
|
+
[React Email 4](https://resend.com/blog/react-email-4) added a compatibility
|
|
86
|
+
checker, also powered by Can I email, to its preview. Its CLI (`email dev`,
|
|
87
|
+
`build`, `start`, `export`) has no check command and no exit code for CI, per
|
|
88
|
+
[its docs](https://react.email/docs/cli). This CLI reads React Email files as
|
|
89
|
+
well as MJML, Maizzle and plain HTML, and fails the build.
|
|
90
|
+
|
|
91
|
+
Beyond CSS support, `lint` checks what neither covers: spam signals, links,
|
|
92
|
+
accessibility, images, the inbox preview text, size, template variables,
|
|
93
|
+
overflow, dark-mode and mobile contrast, Outlook VML, styles a client drops, and
|
|
94
|
+
client-targeting hacks.
|
|
95
|
+
|
|
96
|
+
## Extras
|
|
97
|
+
|
|
98
|
+
### `lint` options
|
|
99
|
+
|
|
100
|
+
| Flag | Alias | Description |
|
|
101
|
+
|------|-------|-------------|
|
|
102
|
+
| `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle`. `.vue` is `maizzle`. A pasted Vue file with no flag is detected. |
|
|
103
|
+
| `--json` | | Output as JSON, one line, every finding including info |
|
|
104
|
+
| `--info` | | List info findings too. By default they are counted, not listed: they are safe fallbacks, not problems |
|
|
105
|
+
| `--fail-on-warning` | | Exit 2 if warnings found |
|
|
106
|
+
| `--max-warnings` | | Fail if more than n warnings |
|
|
107
|
+
| `--reporter github` | | Also print GitHub Actions annotations, so each finding shows on its line in the pull request. Not with `--json` |
|
|
108
|
+
| `--quiet` | `-q` | No line about the hosted preview after a failure |
|
|
109
|
+
| `--skip` | | Comma-separated checks to skip: `spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables,overflow,visual,darkContrast,mobileContrast,design,vml,styleSurvival,targeting` |
|
|
110
|
+
| `--targeting-policy` | | `progressive` (default), `strict`, or `lenient` |
|
|
111
|
+
| `--email-type` | | `transactional` drops the unsubscribe requirement; `marketing` keeps it. Default: `emailType` in `.emailensrc` |
|
|
112
|
+
| `--gate` | | Also send each email to the hosted pre-send gate, which fails on a regression against the last version of that file that passed. Pro plan, needs `EMAILENS_API_KEY` |
|
|
113
|
+
|
|
114
|
+
A `.emailensrc` in the project, the file the VS Code extension reads, can set
|
|
115
|
+
rule severities and skips; `--skip` on the command line wins.
|
|
116
|
+
|
|
117
|
+
Maizzle HTML needs `@maizzle/framework@5` installed beside the CLI. A `.vue`
|
|
118
|
+
file needs `@maizzle/framework@6`. One install is one major.
|
|
119
|
+
|
|
120
|
+
### Other commands
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
emailens analyze email.html # score per client, findings by client
|
|
124
|
+
emailens analyze email.html --clients gmail-web,outlook-windows --json
|
|
125
|
+
emailens audit email.html # compatibility plus every other check
|
|
126
|
+
emailens preview email.html --dark-mode # transforms, analysis, dark mode simulation
|
|
127
|
+
emailens preview email.html --screenshots --out ./shots # needs BROWSERLESS_URL and playwright-core
|
|
128
|
+
emailens export email.html -o ./report # self-contained HTML report (--json for JSON)
|
|
129
|
+
emailens fix email.html -o fixed.html # AI fix, needs ANTHROPIC_API_KEY (--estimate: tokens only)
|
|
130
|
+
emailens clients # the 21 clients
|
|
131
|
+
cat email.html | emailens analyze - # stdin
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### `emailens inbox wait`
|
|
135
|
+
|
|
136
|
+
The CI step for what your app actually sends. Make your app send a real email
|
|
137
|
+
(sign-up, reset, receipt) to your Emailens test inbox, then wait for it. It
|
|
138
|
+
fails when the email is no longer the one you checked in Emailens, or changed
|
|
139
|
+
since it last arrived: a link moved to staging, an emptied variable, a new
|
|
140
|
+
line, an image gone, a size jump, signing that stopped passing. Codes, tokens
|
|
141
|
+
and tracking ids differ on every send and do not count. It needs an API key.
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
export EMAILENS_API_KEY=... # app.emailens.dev/dashboard/api
|
|
145
|
+
SINCE=$(date +%s000) # before the send
|
|
146
|
+
npm run send-signup-email # your app sends it
|
|
147
|
+
emailens inbox wait --subject "Welcome" --since "$SINCE"
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Options: `--subject`, `--sender`, `--inbox <id>`, `--since` (ISO time, epoch
|
|
151
|
+
ms, or a duration such as `5m`; default 2 minutes back), `--timeout` (seconds,
|
|
152
|
+
default 60, at most 600), `--fail-on all|check|drift|none` (default `all`),
|
|
153
|
+
`--json`. Exit codes: `0` pass, `1` changed, `2` nothing arrived or Emailens
|
|
154
|
+
could not be reached.
|
|
155
|
+
|
|
156
|
+
### In your tests
|
|
157
|
+
|
|
158
|
+
The same check as `lint`, as an assertion. It throws with every failing
|
|
159
|
+
finding and its line, reads your `.emailensrc`, and works in Vitest, Jest and
|
|
160
|
+
bun:test.
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
import { render } from "@react-email/render";
|
|
164
|
+
import { expectEmailToPass } from "@emailens/cli/test";
|
|
165
|
+
|
|
166
|
+
test("welcome email passes", async () => {
|
|
167
|
+
expectEmailToPass(await render(<Welcome name="Ada" />));
|
|
168
|
+
});
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Options: `failOnWarning`, `skip` (the `--skip` names), `framework`.
|
|
172
|
+
|
|
173
|
+
### In GitHub Actions
|
|
174
|
+
|
|
175
|
+
```yaml
|
|
176
|
+
- uses: actions/setup-node@v4
|
|
177
|
+
with:
|
|
178
|
+
node-version: 22
|
|
179
|
+
- run: npx -y @emailens/cli lint 'emails/*.html' --fail-on-warning --reporter github
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
`--reporter github` puts each finding on its line in the pull request's
|
|
183
|
+
changed files.
|
|
184
|
+
|
|
185
|
+
`**` globs are not supported: use a single-level wildcard or list the files.
|
|
186
|
+
For scores per client in a pull request comment, use the
|
|
187
|
+
[Action](https://github.com/emailens/action).
|
|
188
|
+
|
|
189
|
+
### Hosted
|
|
190
|
+
|
|
191
|
+
[app.emailens.dev/try](https://app.emailens.dev/try?utm_source=cli&utm_medium=readme)
|
|
192
|
+
renders the email per client: five clients with no account, all 21 with a free
|
|
193
|
+
one. The + Real plans add real-device screenshots: Outlook on Windows and Mac,
|
|
194
|
+
Apple Mail on Mac and iPad, and Gmail, Yahoo and Proton on the web.
|
|
195
|
+
|
|
196
|
+
## Ecosystem
|
|
197
|
+
|
|
198
|
+
| Project | What it is |
|
|
199
|
+
|---|---|
|
|
200
|
+
| [@emailens/engine](https://github.com/emailens/engine) | The analysis engine this CLI runs, as a library |
|
|
201
|
+
| [@emailens/mcp](https://github.com/emailens/mcp) | The same checks for coding agents: `claude mcp add emailens -- npx -y @emailens/mcp` |
|
|
202
|
+
| [emailens/action](https://github.com/emailens/action) | GitHub Action: fails the build, and can comment the scores per client on the pull request |
|
|
203
|
+
| [emailens/vscode](https://github.com/emailens/vscode) | VS Code extension: findings and preview in the editor |
|
|
204
|
+
|
|
205
|
+
## License
|
|
206
|
+
|
|
207
|
+
MIT
|