@email-kit/cli 1.0.1 → 1.1.0

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.
@@ -0,0 +1,214 @@
1
+ <!-- Generated from docs/reference/cli.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
2
+
3
+ # CLI
4
+
5
+ The `email-kit` command comes from `@email-kit/cli`. Run it with `npx email-kit <command>`, or
6
+ through the scripts `init` adds (`npm run email-kit:compile`). It needs Node.js 22.12 or later.
7
+
8
+ | Command | Does |
9
+ |---|---|
10
+ | [`init`](#init) | Add email-kit to a project: a config, a folder and a welcome template |
11
+ | [`new <id>`](#new) | Add a template, with its messages in every locale and a fixture |
12
+ | [`compile`](#compile) | Compile the templates into the output folder (alias: `generate`) |
13
+ | [`check`](#check) | Compile in memory and run the checks; exits 1 on any error |
14
+ | [`tokens`](#tokens) | Print the theme's colour roles with contrast ratios, and its findings |
15
+ | [`agents`](#agents) | Add or update the email-kit skill for AI coding agents |
16
+
17
+ `email-kit --help` lists them, `email-kit <command> --help` shows a command's flags, and
18
+ `email-kit --version` prints the version. Every command except `init` takes `--config <path>` to
19
+ use a config file other than `./email-kit.config.ts`.
20
+
21
+ Errors carry an id in brackets, such as `[placeholder-misuse]`, explained in the
22
+ [error reference](errors.md).
23
+
24
+ ## init
25
+
26
+ ```sh
27
+ npm create email-kit # runs `email-kit init` without installing the CLI first
28
+ npx @email-kit/cli init
29
+ npx email-kit init # with the CLI installed
30
+ ```
31
+
32
+ Run it in the project that sends email; in a monorepo, the app's folder, such as `apps/api`.
33
+ `npm create email-kit` passes its flags on after `--`: `npm create email-kit -- --yes`.
34
+
35
+ `init` shows what it will create and change, asks before each change to an existing file, then
36
+ installs, compiles once, sets up AI coding agents (see [`agents`](#agents)) and prints how to
37
+ render the welcome email. It never writes into a folder that isn't its own. Run it again and it
38
+ says the project is already set up.
39
+
40
+ | Flag | Does |
41
+ |---|---|
42
+ | `--yes` | Accept every default without asking. Use it in CI and scripts, where there's no terminal to ask in |
43
+ | `--dir <path>` | Put the email-kit folder in this code root instead of the detected one |
44
+ | `--config <path>` | Name the config file something other than `email-kit.config.ts` |
45
+ | `--force` | Overwrite an existing config file of that name. A folder that's already set up still stops `init` |
46
+ | `--no-install` | Don't run the package manager after adding the dependencies |
47
+ | `--agents [list]` | Set up these AI coding agents instead of asking, as for [`agents`](#agents). With `--yes`, `init` sets up the agents the repository shows |
48
+ | `--no-agents` | Don't set up AI coding agents |
49
+
50
+ ### What it detects
51
+
52
+ | What | How |
53
+ |---|---|
54
+ | Package manager | The `packageManager` field, else the lockfile (`pnpm-lock.yaml`, `bun.lock`, `yarn.lock`), else npm |
55
+ | Code root | In order: `rootDir` or a single `include` in `tsconfig.json`; the `@/*` or `~/*` path alias; `src/app` or `src/pages` (then `src`); `app` or `pages` (then the project root); a `src/` folder with code; the project root |
56
+ | Host | Bun; a bundler in the dependencies (`next`, `vite`, `tsup`, `esbuild`, `wrangler`, `tsx`, `@remix-run/dev`, `astro`, `nuxt`); a script that runs `node` on a `.ts` file (Node type stripping); a script that runs `tsc` |
57
+ | Schema library | Zod, Valibot or ArkType in the dependencies, else Zod |
58
+ | shadcn theme | A CSS file with `--primary` in `:root`: the one `components.json` names, or `app/globals.css` and similar. `init` asks whether to use it as the email theme |
59
+ | AI coding agents | Their files in the repository root or the project: `CLAUDE.md` or `.claude/` (Claude Code), `.codex/` (Codex), `.cursor/` (Cursor), `.github/copilot-instructions.md` and similar (GitHub Copilot), `GEMINI.md` or `.gemini/` (Gemini CLI), `.agent/` or `.agents/rules/` (Antigravity), `.windsurf/` (Windsurf), `AGENTS.md` or `.agents/skills/` (any agent that reads `AGENTS.md`) |
60
+
61
+ The host decides how your app imports the emails:
62
+
63
+ | Host | Import | How |
64
+ |---|---|---|
65
+ | A bundler or Bun, with a `tsconfig.json` | `@/email-kit` | Your `@/*` alias if it already reaches the folder; otherwise `init` adds the path `@/email-kit` to `tsconfig.json` |
66
+ | A `tsc` build run with `node` | `#email-kit` | `"imports"` in `package.json`, pointing at `_generated/index.mjs`; the config gets `module: "mjs"` |
67
+ | Node type stripping | `#email-kit` | `"imports"` in `package.json`, pointing at the folder's `index.ts` |
68
+ | Anything else | `./email-kit` | A relative import |
69
+
70
+ The import path is saved as `importPath` in the config, so `email-kit new` prints examples with it.
71
+
72
+ ### What it creates and changes
73
+
74
+ ```
75
+ email-kit.config.ts the config: locales, sender values, import path
76
+ src/email-kit/
77
+ index.ts re-exports ./_generated: what your app imports
78
+ welcome/
79
+ template.tsx a welcome email that shows each part of a template
80
+ messages.en.json
81
+ _generated/ written by `email-kit compile`
82
+ ```
83
+
84
+ The folder is the first free one of `email-kit`, `email-templates` and `emails` in the code root.
85
+ Without a `src/` folder it sits at the project root.
86
+
87
+ With your agreement, `init` also:
88
+
89
+ - adds `@email-kit/runtime` as a dependency, and `@email-kit/cli`, `@email-kit/core`,
90
+ `@email-kit/components` and the schema library as devDependencies (Valibot also gets
91
+ `@valibot/to-json-schema`);
92
+ - adds the scripts `email-kit:compile`, `email-kit:check` and `email-kit:watch`
93
+ (`email-kit compile --watch`), or the same under the prefix `emails:` or `ek:` if those are
94
+ taken;
95
+ - adds `"jsx": "react-jsx"` to `tsconfig.json` when it has no JSX setting. Such a project has no
96
+ JSX of its own, so `init` also adds `"jsxImportSource": "@email-kit/core"`, and templates don't
97
+ need the `@jsxImportSource` line. A solution-style tsconfig (one with `references`) gets only
98
+ `jsx`;
99
+ - marks the `_generated` folder as generated in `.gitattributes`, and ignores it in
100
+ `.prettierignore` and `.eslintignore` if you have them.
101
+
102
+ Only `@email-kit/runtime` is a dependency, because the generated module imports it when your app
103
+ runs. It has no dependencies of its own and adds about 1.5 KB to 3 KB to a bundle, minified and
104
+ gzipped. The rest is only needed to compile.
105
+
106
+ ## new
107
+
108
+ ```sh
109
+ npx email-kit new password-reset
110
+ ```
111
+
112
+ Creates the folder `password-reset/` in the email-kit folder, with a `template.tsx` holding a
113
+ schema, a fixture and a few components, and a `messages.<locale>.json` for every locale in the
114
+ config. Ids are lowercase words joined by hyphens. An id that's in use is refused, never
115
+ overwritten. The template becomes `emails.passwordReset` after the next compile. It starts with
116
+ the `@jsxImportSource` line unless your tsconfig sets `"jsxImportSource": "@email-kit/core"`.
117
+
118
+ | Flag | Does |
119
+ |---|---|
120
+ | `--config <path>` | Use this config file |
121
+
122
+ ## compile
123
+
124
+ ```sh
125
+ npx email-kit compile
126
+ ```
127
+
128
+ Writes the output folder, `_generated/` by default:
129
+
130
+ ```
131
+ _generated/
132
+ index.ts the module your app imports (index.mjs + index.d.mts with module: "mjs")
133
+ messages.d.ts the types that make t() typed in templates
134
+ ```
135
+
136
+ The compiler owns the folder: each compile removes anything it didn't write. Config options add
137
+ more files: `contract` (each email's parts as files, for other backends), `perTemplateEntries`
138
+ (a module per template) and `theme.emit` (`theme.json`). See [Configuration](configuration.md).
139
+
140
+ On an error, nothing is written and the command exits 1. `email-kit generate` is the same
141
+ command.
142
+
143
+ | Flag | Does |
144
+ |---|---|
145
+ | `--watch` | Recompile when a template, component, message or the config changes |
146
+ | `--quiet` | Print errors only |
147
+ | `--verbose` | Also print each template's sizes per locale, and the files that changed |
148
+ | `--config <path>` | Use this config file |
149
+
150
+ ## check
151
+
152
+ ```sh
153
+ npx email-kit check
154
+ ```
155
+
156
+ Compiles in memory (it writes nothing) and runs the [checks](checks.md) over the compiled emails,
157
+ the renders of every fixture and generated variant, the template sources, the theme and the
158
+ project. It exits 1 on any error, and 0 when there are only warnings and notes. See
159
+ [Checks and CI](../guide/checks-and-ci.md).
160
+
161
+ | Flag | Does |
162
+ |---|---|
163
+ | `--reporter <name>` | `human` (the default), `json` or `github`, which writes annotations for GitHub Actions |
164
+ | `--json` | The same as `--reporter json`: the findings in a versioned JSON schema |
165
+ | `--config <path>` | Use this config file |
166
+
167
+ ## tokens
168
+
169
+ ```sh
170
+ npx email-kit tokens
171
+ ```
172
+
173
+ Prints the theme's colour roles in light and dark with their contrast ratios, then the theme's
174
+ findings. It exits 1 when a `tokens.*` check fails at error level. See
175
+ [Theme and dark mode](../guide/theme.md#see-the-resolved-theme).
176
+
177
+ | Flag | Does |
178
+ |---|---|
179
+ | `--config <path>` | Use this config file |
180
+
181
+ ## agents
182
+
183
+ ```sh
184
+ npx email-kit agents
185
+ ```
186
+
187
+ Writes the email-kit skill for the AI coding agents you use, and a short section in each one's
188
+ instructions file that points to it. See [AI coding agents](https://email-kit.dev/guide/ai-agents).
189
+
190
+ It asks which agents to set up, with the ones the repository shows already selected (see
191
+ [What it detects](#what-it-detects)), then writes, at the root of the repository:
192
+
193
+ | Path | For | What |
194
+ |---|---|---|
195
+ | `.agents/skills/email-kit/` | Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, Windsurf and others | The skill, `SKILL.md`, which links to the documentation the CLI ships, in `node_modules/@email-kit/cli/dist/docs/` |
196
+ | `.claude/skills/email-kit/` | Claude Code | The same skill |
197
+ | `AGENTS.md` | Agents that read it, and Claude Code when there's no `CLAUDE.md` | A section between `<!-- email-kit:start -->` and `<!-- email-kit:end -->`: where the emails are, the commands, and the skill to read |
198
+ | `CLAUDE.md` | Claude Code, when the repository has one | The same section |
199
+ | `GEMINI.md` | Gemini CLI | The same section |
200
+
201
+ It creates the files that don't exist and asks before changing one that does. Run again, it
202
+ replaces its own section and skill folders and nothing else, and removes files an older skill had.
203
+ It never writes into a skill folder it didn't create. In a monorepo the section names the app, so
204
+ each app keeps its own.
205
+
206
+ `SKILL.md` records the version that wrote it, as `metadata.email-kit-version`. `email-kit check`
207
+ warns when a copy differs from the one the installed CLI ships
208
+ ([`agents.skill-outdated`](checks.md#agentsskill-outdated)): run `email-kit agents` after upgrading.
209
+
210
+ | Flag | Does |
211
+ |---|---|
212
+ | `--agents <list>` | These agents instead of asking, separated by commas: `claude`, `codex`, `cursor`, `copilot`, `gemini`, `antigravity`, `windsurf`, `agents-md` (any other agent that reads `AGENTS.md`), `all` or `none` |
213
+ | `--yes` | Take the agents the repository shows and accept every change without asking. It exits 1 when it finds none: name them with `--agents` |
214
+ | `--config <path>` | Use this config file |
@@ -0,0 +1,115 @@
1
+ <!-- Generated from docs/reference/configuration.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
2
+
3
+ # Configuration
4
+
5
+ The config is `email-kit.config.ts` in the project root (`.mts`, `.js` and `.mjs` work too), with
6
+ `defineConfig()` as its default export. Commands look for it in the current folder; `--config
7
+ <path>` points them elsewhere.
8
+
9
+ ```ts
10
+ import { defineConfig } from "@email-kit/core"
11
+
12
+ export default defineConfig({
13
+ locales: { default: "en", list: ["en", "de"] },
14
+ sender: {
15
+ productName: "Acme",
16
+ legalName: "Acme Ltd",
17
+ postalAddress: "1 High Street, London",
18
+ helpUrl: "https://help.acme.example",
19
+ privacyUrl: "https://acme.example/privacy",
20
+ siteUrl: { runtime: true },
21
+ },
22
+ theme: { source: "app/globals.css" },
23
+ checks: {
24
+ "output.gitignored": { level: "off", reason: "The build compiles the emails before deploying" },
25
+ },
26
+ })
27
+ ```
28
+
29
+ Paths are relative to the config file. An unknown option, or one with the wrong type, fails every
30
+ command with [`invalid-config`](errors.md#invalid-config), listing each problem.
31
+
32
+ ## Options
33
+
34
+ | Option | Type | Default | |
35
+ |---|---|---|---|
36
+ | `root` | `string` | `src/email-kit` if there's a `src/` folder, else `email-kit` | The email-kit folder: a folder per template, `<root>/<id>/template.tsx`, with `messages.<locale>.json` beside it |
37
+ | `out` | `string` | `<root>/_generated` | The output folder. The compiler owns it: each compile removes what it didn't write (names starting with `.` stay). It can't be or contain the email-kit folder, or contain the project, and a folder with files email-kit didn't write is refused |
38
+ | `contract` | `boolean` | `false` | Also write each email's parts as files, for backends that don't run the module: `<out>/<id>/<locale>.html` and `.txt`, `<out>/<id>/schema.json` and `<out>/manifest.json`. See [Other backends](../guide/sending.md#other-backends) |
39
+ | `module` | `"ts"` or `"mjs"` | `"ts"` | The generated module: `index.ts`, or `index.mjs` with `index.d.mts` for projects built with plain `tsc` |
40
+ | `perTemplateEntries` | `boolean` | `false` | Also write a self-contained module per template, `<out>/<id>/index.ts`, so a function that sends one email bundles only that one |
41
+ | `validate` | `boolean` | `true` | `render()` validates data against the schema before rendering. `validate()` is there either way |
42
+ | `importPath` | `string` | | How your app imports the emails, such as `@/email-kit` or `#email-kit`. `init` sets it; `email-kit new` uses it in the examples it prints |
43
+ | `locales` | object | `{ default: "en" }` | See [Locales](#locales) |
44
+ | `sender` | object | `{}` | See [Sender values](#sender-values) |
45
+ | `theme` | object | the built-in theme | See [Theme](#theme) |
46
+ | `checks` | object | `{}` | Per-check levels. See [Checks](#checks) |
47
+ | `customChecks` | `CustomCheck[]` | `[]` | Your team's checks. See [Checks](#checks) |
48
+
49
+ ## Locales
50
+
51
+ | Field | Type | Default | |
52
+ |---|---|---|---|
53
+ | `default` | `string` | `"en"` | The locale `render()` falls back to |
54
+ | `list` | `string[]` | only the default | Every locale to compile. It must include the default |
55
+ | `fallback` | `{ [tag]: locale }` | `{}` | Where a requested locale goes when no compiled locale matches it, before CLDR's parents. Each key must not be compiled; each value must be |
56
+ | `pseudo` | `boolean`, or a list of `"en-XA"` and `"ar-XB"` | `false` | Also compile and ship the pseudo-locales. `email-kit check` builds them either way |
57
+
58
+ Tags must be canonical BCP 47: `en`, `pt-BR`, `zh-Hant`. See
59
+ [Messages and locales](../guide/messages.md#locales).
60
+
61
+ ## Sender values
62
+
63
+ ```ts
64
+ sender: {
65
+ productName: "Acme",
66
+ siteUrl: { runtime: true },
67
+ }
68
+ ```
69
+
70
+ The keys are `productName`, `name`, `legalName`, `postalAddress`, `privacyUrl`, `helpUrl`,
71
+ `supportEmail` and `siteUrl`. Each value is a non-empty string, written into the output when you
72
+ compile, or `{ runtime: true }`, passed by your backend to
73
+ [`createEmails()`](../guide/sending.md#runtime-sender-values) at send time. Templates read them as
74
+ `sender.<key>`; see [Sender values](../guide/templates.md#sender-values).
75
+
76
+ `siteUrl`, `helpUrl` and `privacyUrl` must be `https://` URLs and `supportEmail` an email address,
77
+ whether set here or passed at send time.
78
+
79
+ ## Theme
80
+
81
+ | Field | Type | Default | |
82
+ |---|---|---|---|
83
+ | `source` | see [Sources](../guide/theme.md#sources) | the built-in theme | Where the colours come from |
84
+ | `input` | `{ [modifier]: context }` | each modifier's default | For a DTCG resolver source only: the context of each modifier besides light and dark, such as `{ brand: "acme" }` |
85
+ | `roles` | `{ [role]: colour }` | | Override a [role](../guide/theme.md#roles) with a CSS colour or a `"{token}"` from the source, for both modes or `{ light, dark }` |
86
+ | `typography.stacks` | `{ sans?, serif?, mono? }` | system stacks | Font families in order, ending in a generic family. The last named family is classic Outlook's fallback |
87
+ | `typography.scale` | `{ [step]: Partial<TypeStyle> }` | see [Type scale](../guide/theme.md#type-scale) | Override steps of the type scale |
88
+ | `radius` | `number` | the source's `--radius`, else 10 | The base radius in px |
89
+ | `layout.container` | `number` | `600` | The width of the centred container, in px. Keep it within 480–640 (`tokens.container`) |
90
+ | `dark` | `"authored"` or `"none"` | `"authored"` if the source has a dark palette, else `"none"` | Whether the email carries your dark palette |
91
+ | `emit` | `boolean` | `false` | Also write the resolved theme to `<out>/theme.json` |
92
+
93
+ Every colour is converted to 6-digit hex, since email clients don't all read modern colour syntax:
94
+ out-of-gamut colours are mapped into sRGB, and translucent ones are flattened onto the surface they
95
+ sit on.
96
+
97
+ See [Theme and dark mode](../guide/theme.md) for the sources, roles, type scale and dark mode.
98
+
99
+ ## Checks
100
+
101
+ ```ts
102
+ checks: {
103
+ "img.fluid-width": { level: "off", reason: "Hero images are fixed width by design" },
104
+ }
105
+ ```
106
+
107
+ Each key is a check id from the [checks reference](checks.md), or a team check's id:
108
+
109
+ | Field | Type | |
110
+ |---|---|---|
111
+ | `level` | `"off"`, `"info"`, `"warn"` or `"error"` | `error` fails `check` (exit 1); `warn` and `info` are reported only |
112
+ | `reason` | `string` | Required, and not empty |
113
+
114
+ `customChecks` takes checks made with `defineCheck()`. See
115
+ [Checks and CI](../guide/checks-and-ci.md#team-checks).
@@ -0,0 +1,264 @@
1
+ <!-- Generated from docs/reference/errors.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
2
+
3
+ # Error reference
4
+
5
+ Every error email-kit reports has an id, shown in brackets:
6
+
7
+ ```
8
+ ✗ src/email-kit/order/template.tsx:12:15 [placeholder-misuse]
9
+ ```
10
+
11
+ Each id below says why it happens and how to fix it. The CLI links to these entries (CLI-06).
12
+ A test checks that every id the code can raise is listed here.
13
+
14
+ ## Setup (`email-kit init`)
15
+
16
+ ### no-package-json
17
+ **Why:** `init` works on the nearest folder with a `package.json`, and there's none from here up.
18
+ **Fix:** run it inside the project that sends email, such as `apps/api` in a monorepo.
19
+
20
+ ### init-needs-answers
21
+ **Why:** `init` or `email-kit agents` asks before it changes files, and there's no terminal to ask in (CI, a script).
22
+ **Fix:** run it with `--yes` to accept the defaults. For `init`, `--dir`, `--config`, `--no-install` and `--agents` set the rest; for `agents`, `--agents` names the agents.
23
+
24
+ ### init-cancelled
25
+ **Why:** a question was cancelled (Ctrl+C). Files created before it stay; nothing after it was changed.
26
+ **Fix:** run `email-kit init` again: it says "already set up" if the config was written, and `email-kit new` adds templates.
27
+
28
+ ## Config
29
+
30
+ ### config-not-found
31
+ **Why:** `email-kit compile` looks for `email-kit.config.ts` (or `.mts`, `.js`, `.mjs`) in the current folder.
32
+ **Fix:** run the command from the project root, create the config with `npx email-kit init`, or pass `--config <path>`.
33
+
34
+ ### invalid-config
35
+ **Why:** the config has unknown options, paths that overlap, or locale tags that aren't canonical BCP 47 (such as `en_US` or `pt-br`). Every problem is listed with its path.
36
+ **Fix:** correct each listed option. Locale tags take the form `en`, `pt-BR` or `zh-Hant`, and the list must include the default locale.
37
+
38
+ ### no-templates-folder
39
+ **Why:** the email-kit folder (`root`: `src/email-kit` or `email-kit` by default), which holds a folder per template, doesn't exist.
40
+ **Fix:** create it, or set `root` in the config.
41
+
42
+ ### old-layout
43
+ **Why:** the email-kit folder still has a `templates/` folder of `.tsx` files. Each template is now a folder of its own, named by its id, with its messages beside it.
44
+ **Fix:** move `templates/<id>.tsx` to `<id>/template.tsx`, and `messages/<locale>/<id>.json` to `<id>/messages.<locale>.json`. Remove `templates` and `messages` from the config if they're set.
45
+
46
+ ### out-not-owned
47
+ **Why:** each compile replaces everything in the output folder (`out`, `<root>/_generated` by default), and this one has files email-kit didn't write. email-kit recognises its own folder by the "Generated by email-kit" header of the module it writes.
48
+ **Fix:** set `out` to a new or empty folder, or empty this one. Names starting with `.`, such as `.gitkeep`, are left alone.
49
+
50
+ ### missing-template
51
+ **Why:** a folder in the email-kit folder has `messages.<locale>.json` files but no `template.tsx`, so it isn't compiled. The template file is usually missing or misnamed.
52
+ **Fix:** add or rename the file to `template.tsx`. If the folder isn't a template, start its name with `_`.
53
+
54
+ ## Loading files
55
+
56
+ ### syntax-error
57
+ **Why:** a template, a component or the config doesn't parse.
58
+ **Fix:** fix the code at the reported line. The code frame shows where the parser stopped.
59
+
60
+ ### unresolved-import
61
+ **Why:** an import can't be found from the file that imports it.
62
+ **Fix:** check the path, and install the package if it is one. Aliases come from the project's tsconfig `paths`.
63
+
64
+ ### load-failed
65
+ **Why:** a file failed to load or run for a reason email-kit doesn't recognise, such as an exception thrown at the top level of a template.
66
+ **Fix:** read the message and the reported location. If it points into email-kit itself, please report it.
67
+
68
+ ### no-definition
69
+ **Why:** a `template.tsx` doesn't `export default defineEmail({ … })`.
70
+ **Fix:** add the default export. Helpers that aren't templates go in a folder whose name starts with `_`, such as `_shared/`.
71
+
72
+ ## Templates
73
+
74
+ ### invalid-id
75
+ **Why:** template ids are lowercase words joined by hyphens (`order-confirmation`), because they become file names and code identifiers.
76
+ **Fix:** rename the id. Never rename an id that has shipped: backends call it by name.
77
+
78
+ ### invalid-purpose
79
+ **Why:** every template declares its legal purpose, `"transactional"`, `"marketing"` or `"consent-request"`, because it decides which footer parts the `legal.*` checks require (`legal.purpose-declared`).
80
+ **Fix:** add `purpose` to `defineEmail()`. Any promotional content makes an email `"marketing"`.
81
+
82
+ ### duplicate-id
83
+ **Why:** `email-kit new` was given an id whose folder exists. Each template's folder is its id, so two templates can't share one.
84
+ **Fix:** choose another id.
85
+
86
+ ### id-mismatch
87
+ **Why:** a template's folder is its id, and `defineEmail({ id })` names a different one. The id in `defineEmail()` types `t()`, so the two must agree.
88
+ **Fix:** rename the folder to the id, or change the id to the folder's name. Never rename an id that has shipped: backends call it by name.
89
+
90
+ ### identifier-collision
91
+ **Why:** two ids become the same key in the generated `emails` object.
92
+ **Fix:** rename one of the templates.
93
+
94
+ ### static-condition
95
+ **Why:** `<If>`, `<Unless>` and `<Each>` choose content at send time, so they need a field from `data`.
96
+ **Fix:** for conditions known at compile time, use plain JavaScript: `{isMarketing && <Footer />}`.
97
+
98
+ ### list-condition
99
+ **Why:** `<If>` was given a list. A list section repeats its content once per item, so the content
100
+ would show as many times as the list has items.
101
+ **Fix:** use `<Each>` for the items (it shows nothing for an empty or missing list) and `<Unless>`
102
+ for the empty case. For content around the items, such as a heading or a `<List>`, wrap the list
103
+ in an optional object and test that with `<If>`, or pass a boolean field such as `hasItems`.
104
+
105
+ ### function-child
106
+ **Why:** a function was rendered as a child. Only `<Each>` and `<If>` take a function child.
107
+ **Fix:** call the function, or move it inside `<Each>` or `<If>`.
108
+
109
+ ### invalid-child
110
+ **Why:** a child has a type that can't be rendered (an object, a symbol).
111
+ **Fix:** render strings, numbers, placeholders, elements or arrays of them.
112
+
113
+ ### invalid-attribute
114
+ **Why:** an attribute or the subject got a value that can't be text: an element, or an object.
115
+ **Fix:** use strings, numbers, placeholders or a message from `t()`. The subject is text only.
116
+
117
+ ### data-dependent-style
118
+ **Why:** styles are fixed when the template compiles, so a `style` value can't come from `data`.
119
+ **Fix:** choose between fixed styles with `<If>` and `<Unless>`.
120
+
121
+ ### sender-value-missing
122
+ **Why:** the template reads `sender.<key>`, but the config doesn't set that sender value.
123
+ **Fix:** set it in `email-kit.config.ts`: `sender: { productName: "Acme" }` for a fixed value, or `sender: { siteUrl: { runtime: true } }` for one the backend passes to `createEmails()` at send time.
124
+
125
+ ### no-theme
126
+ **Why:** a component called `useTheme()` (or styled with `role(…)`) outside a compile, for example from a test that called it directly.
127
+ **Fix:** compile the template with `email-kit compile`, or through the compiler API, which provides the theme.
128
+
129
+ ### outside-evaluation
130
+ **Why:** `<Each>`, `<If>` or `<Unless>` ran outside a compile, for example from a test that called the component directly.
131
+ **Fix:** compile the template with `email-kit compile`, or through the compiler API.
132
+
133
+ ## Components
134
+
135
+ ### invalid-image
136
+ **Why:** an `<Image>` prop breaks a rule clients enforce: `width` and `height` must be whole px (Word ignores CSS widths), an informative or functional image needs alt text, and a literal `src` must be an absolute `https:` URL to a PNG, JPEG or GIF. SVG shows blank in Outlook on the web and new Outlook; classic Outlook can't show WebP or AVIF.
137
+ **Fix:** follow the message: export a PNG or JPEG, use the `https:` URL, give the alt text, or use `kind="decorative"` for an image that adds nothing.
138
+
139
+ ### invalid-table
140
+ **Why:** a `<DataTable>` has fewer than two columns. NVDA with classic Outlook treats one-column tables as layout and stops announcing headers, and a single column reads better as a list.
141
+ **Fix:** use `KeyValue` or `List`, or add the column the data needs.
142
+
143
+ ## Fixtures
144
+
145
+ ### invalid-fixture
146
+ **Why:** a fixture in `defineEmail({ fixtures })` doesn't match the template's schema. `email-kit check` renders them, so they must be data the backend could send.
147
+ **Fix:** correct the fixture at the path in the message, or the schema if the fixture shows real data it doesn't allow yet.
148
+
149
+ ## Checks
150
+
151
+ ### check-failed
152
+ **Why:** a team check in `customChecks` threw while `email-kit check` ran it. The message names the check and repeats its error.
153
+ **Fix:** fix the check's `run()`. It gets plain data: guard for elements or attributes that may be missing.
154
+
155
+ ## Data and placeholders
156
+
157
+ ### placeholder-misuse
158
+ **Why:** at compile time `data` holds placeholders, not values. Arithmetic, string methods, template literals, `.map()` and spreading need the real value, which only exists at send time.
159
+ **Fix:** compute the value in the backend and pass it as its own field. Use `<Each of={…}>` for lists.
160
+
161
+ ### non-scalar-placeholder
162
+ **Why:** `data` itself, or an object field, was rendered where text belongs.
163
+ **Fix:** render one of its scalar fields.
164
+
165
+ ### invalid-field-name
166
+ **Why:** field names become placeholder names and code identifiers in every language, so they are limited to letters, digits and `_`.
167
+ **Fix:** rename the field in the schema, for example `firstName` instead of `first-name`.
168
+
169
+ ### shadowed-item
170
+ **Why:** inside a nested `<Each>` or `<If>`, `{{.}}` means the innermost value, so an outer list item can't be reached through it.
171
+ **Fix:** use a list of objects and a field of the item, or restructure so the item is used in its own `<Each>`.
172
+
173
+ ## Messages
174
+
175
+ ### missing-message
176
+ **Why:** `t("key")` asks for a message that the locale's message file doesn't have. Every locale needs every key (I18N-03).
177
+ **Fix:** add the key to the file named in the error (`<messages>/<locale>/<template>.json`).
178
+
179
+ ### missing-message-param
180
+ **Why:** the message uses `{name}`, but `t()` didn't pass `name`.
181
+ **Fix:** pass the parameter, or remove it from the message.
182
+
183
+ ### unused-message-param
184
+ **Why:** `t()` passed a parameter that the message doesn't use, which usually means a typo in one of them.
185
+ **Fix:** use it in the message, or stop passing it.
186
+
187
+ ### unsupported-message
188
+ **Why:** the message uses ICU syntax email-kit doesn't support: a `number`, `date` or `time` argument (or another type besides `plural` and `select`), or a plural `offset:`.
189
+ **Fix:** format numbers, dates and times in your backend and pass the text, marked with `formatted()` in the schema (see [the formatting recipe](../guide/formatting.md)); write plurals without an offset.
190
+
191
+ ### invalid-message
192
+ **Why:** a message has an unbalanced `{` or `}`.
193
+ **Fix:** balance the braces.
194
+
195
+ ### invalid-plural
196
+ **Why:** a `{n, plural, …}` message can't be compiled for a locale. It lacks a category the locale uses (ADR 0003 requires them all, so no number falls through), names one the locale never uses (English has no `zero`; write `=0` for exactly zero), has an `=N` that isn't a whole number, or gets something other than a number field from data or a literal number.
197
+ **Fix:** add the categories the message names for that locale, such as `one` and `other` in English or `zero`, `one`, `two`, `few`, `many` and `other` in Arabic, or pass a number field.
198
+
199
+ ### invalid-select
200
+ **Why:** a `{x, select, …}` message gets a field without fixed values, or has a case that isn't one of the field's values. The generated module can only prepare the branch for values the schema lists.
201
+ **Fix:** make the field an enum (`z.enum(["free", "pro"])`) and name its values as cases, plus `other`.
202
+
203
+ ### invalid-messages
204
+ **Why:** a message file isn't valid JSON, or isn't a flat object of `"key": "message"` strings.
205
+ **Fix:** correct the file named in the error.
206
+
207
+ ## Text part and subject
208
+
209
+ ### literal-braces
210
+ **Why:** the plain-text part and the subject can't express a literal `{{`, or a `{` right before a placeholder: the placeholder language would read them as a tag.
211
+ **Fix:** rephrase the copy, or put the brace after a space.
212
+
213
+ ### multi-line
214
+ **Why:** the subject and the preheader are a single line.
215
+ **Fix:** remove the line break.
216
+
217
+ ## Schemas
218
+
219
+ ### schema-not-portable
220
+ **Why:** the data schema uses something that Python, Go and other backends can't represent: a union, a record, a tuple, `Date`, `bigint`, `any`, a default or a transform (R4). Each issue is listed with its field path.
221
+ **Fix:** reshape the field. Dates and money arrive as strings the backend formats (R5).
222
+
223
+ ### unsupported-schema
224
+ **Why:** the schema library has no JSON Schema support email-kit can use.
225
+ **Fix:** use Zod 4, ArkType 2, or Valibot with `@valibot/to-json-schema`.
226
+
227
+ ### missing-converter
228
+ **Why:** Valibot schemas need the official converter.
229
+ **Fix:** `npm install -D @valibot/to-json-schema`.
230
+
231
+ ## Themes
232
+
233
+ ### invalid-theme
234
+ **Why:** the theme source can't be used. A shadcn CSS file isn't valid CSS, has no `:root { --… }` variables, or its `var()` references form a cycle. A DTCG token file isn't valid JSON, or an alias points at no token or forms a cycle. A `.resolver.json` breaks a rule of the DTCG Resolver Module: an unknown `version`, a modifier with fewer than two contexts or a `default` that isn't one of them, a `$ref` that points at nothing (or at a modifier from a set, or into `resolutionOrder`), an inline entry without `name` and `type`, a cycle, or a `theme.input` naming an unknown modifier or context.
235
+ **Fix:** correct the file or the input named in the error. A shadcn theme is the CSS that `shadcn init` writes (`app/globals.css` or similar). For a resolver, `theme.input` picks every modifier except the one with `light` and `dark` contexts, which email-kit resolves both of.
236
+
237
+ ### invalid-colour
238
+ **Why:** a theme value isn't a CSS colour email-kit can convert (`oklch()`, `rgb()`, `hsl()`, `color(display-p3 …)`, hex or a named colour).
239
+ **Fix:** use one of those forms. Every colour is converted to 6-digit hex for email clients.
240
+
241
+ ### translucent-colour
242
+ **Why:** a colour with alpha was used where there is no surface to flatten it onto. Email clients don't support `rgba()` or `opacity` everywhere, so translucent colours are composited at build time.
243
+ **Fix:** make the colour opaque, or use it for a role that sits on a surface (borders and text sit on the canvas).
244
+
245
+ ### unresolved-role
246
+ **Why:** a colour role has no value in a mode: the theme lacks the token it maps from, and there is no default.
247
+ **Fix:** add the variable named in the error to the theme, or override the role in the config.
248
+
249
+ ## Output
250
+
251
+ ### invalid-output
252
+ **Why:** the compiler produced something it shouldn't have, such as an invalid placeholder template. This is a bug in email-kit.
253
+ **Fix:** please report it, with the template that triggers it.
254
+
255
+ ## At send time
256
+
257
+ These come from the generated module in a backend, not from the CLI, as an `EmailRenderError` from `@email-kit/runtime`.
258
+
259
+ - **`missing-value`, `non-scalar-value`, `invalid-number`:** from the placeholder renderer, when the data doesn't match the template. See the [mustache-core spec](mustache-core.md#10-errors).
260
+ - **`invalid-data`:** with validation on (the default), the data passed to `render()` doesn't match the template's schema. The error's `issues` list each problem with its path, such as `items[1].qty: expected a number, got "2"`. Call `validate(data)` to check data without rendering, for example when it arrives from a queue.
261
+ - **`missing-context`:** `createEmails()` was called without a value the config marks `{ runtime: true }`, or with an empty one. Pass every runtime key as a non-empty string.
262
+ - **`invalid-context`:** a value passed to `createEmails()` isn't what that sender value has to be: `siteUrl`, `helpUrl` and `privacyUrl` must be `https://` URLs and `supportEmail` an email address, the same rules the config applies to values set there.
263
+ - **`subject-line-break`:** the rendered subject contains CR or LF, usually from user data, and could inject mail headers. Strip line breaks from the value before rendering.
264
+ - **`incompatible-module`:** `createEmails()` found that the module was compiled for another format of `@email-kit/runtime` than the one installed. Install `@email-kit/runtime` at the same version as `@email-kit/cli`, and run `email-kit compile`.