@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,340 @@
1
+ <!-- Generated from docs/reference/mustache-core.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
2
+
3
+ # mustache-core v1
4
+
5
+ **Dialect id:** `mustache-core@1` · **Status:** draft. It becomes final with the first stable
6
+ release; until then, cases may change. The decision behind it is
7
+ [ADR 0002](https://github.com/email-kit/email-kit/blob/main/docs/adr/0002-mustache-core-dialect.md).
8
+
9
+ mustache-core is the placeholder language of compiled email-kit templates. The compiler writes it;
10
+ a small runtime in each backend language renders it at send time. This document defines the dialect. The conformance suite in
11
+ [`conformance/mustache-core/`](https://github.com/email-kit/email-kit/blob/main/conformance/mustache-core/) defines the exact bytes. When the
12
+ two disagree, that is a bug in one of them, and the fix goes into both.
13
+
14
+ The TS reference renderer is [`packages/dialect`](https://github.com/email-kit/email-kit/blob/main/packages/dialect/src/index.ts).
15
+
16
+ ## 1. Goals
17
+
18
+ - **Same bytes in every language.** The same template and data give identical output in TS,
19
+ Python, Go and any later runtime. Everything a language would otherwise decide for itself
20
+ (truthiness, number printing, escaping) is fixed here.
21
+ - **Small enough to write in a day.** A runtime is about 200 lines with no dependencies.
22
+ - **A subset of Mustache.** Every mustache-core template is a valid
23
+ [Mustache](https://github.com/mustache/spec) template. Section 13 lists where stock engines
24
+ render it differently.
25
+ - **Fail loudly.** A missing value is an error, never a silent blank.
26
+
27
+ ## 2. Terms
28
+
29
+ | Term | Meaning |
30
+ |---|---|
31
+ | **Template** | A string of text and tags |
32
+ | **Tag** | `{{…}}` or `{{{…}}}` |
33
+ | **Data** | The root value passed to render, usually an object |
34
+ | **Context stack** | The values that names are looked up in, innermost last. It starts as `[data]` |
35
+ | **Nothing** | The result of a lookup that finds no key, or finds the value `null` |
36
+ | **Profile** | The escaping rules for a template part: `html` or `text` (section 9) |
37
+
38
+ ## 3. Data model
39
+
40
+ Data is a JSON value: null, boolean, number, string, array or object. A runtime converts its
41
+ language's values to this model before lookup:
42
+
43
+ - **Objects** are maps from string keys to values. Only the object's own keys exist: nothing is
44
+ inherited from prototypes or classes, and `{{constructor}}` on `{}` finds nothing.
45
+ - **Arrays** have no keys. `{{items.length}}` and `{{items.0}}` find nothing or are invalid.
46
+ - **Strings** have no keys. `{{name.length}}` finds nothing.
47
+ - **Numbers** are IEEE 754 binary64 doubles. A runtime with integer or decimal types converts them
48
+ to the nearest double first (`9007199254740993` becomes `9007199254740992`). NaN and the
49
+ infinities are invalid (`invalid-number`).
50
+ - A missing key (or `undefined`, `None`, a nil pointer) and `null` are the same: **nothing**.
51
+
52
+ ## 4. Syntax
53
+
54
+ Delimiters are always `{{` and `}}`. They can't be changed.
55
+
56
+ | Form | Meaning |
57
+ |---|---|
58
+ | `{{name}}` | Variable: the value, escaped by the profile |
59
+ | `{{{name}}}` | Raw variable: the value, never escaped |
60
+ | `{{#name}}…{{/name}}` | Section |
61
+ | `{{^name}}…{{/name}}` | Inverted section |
62
+
63
+ **Names.** A name is `.` (the implicit iterator: the current context) or a dotted path:
64
+
65
+ ```
66
+ name = "." / segment *( "." segment )
67
+ segment = ( ALPHA / "_" ) *( ALPHA / DIGIT / "_" ) ; ASCII only
68
+ ```
69
+
70
+ Names are case-sensitive. `items.0`, `first-name`, `a..b` and `a.` are invalid (`invalid-name`).
71
+
72
+ **Inside a tag:**
73
+ - The sigil (`#`, `^`, `/`) must be the first character after `{{`.
74
+ - Spaces (U+0020) and tabs (U+0009) around the name are ignored: `{{ name }}`, `{{# items }}`,
75
+ `{{{ html }}}`. No other whitespace is allowed.
76
+ - `{{{` starts a raw tag that ends at the next `}}}`. `{{` starts any other tag, which ends at the
77
+ next `}}`. A tag with no end is `unclosed-tag`.
78
+
79
+ **Not supported.** These raise `unsupported-tag`:
80
+ - comments `{{! }}`
81
+ - partials `{{> }}`
82
+ - set delimiters `{{= =}}`
83
+ - `{{& }}` (use `{{{ }}}`)
84
+ - inheritance `{{< }}` and `{{$ }}`
85
+
86
+ Lambdas, helpers and filters don't exist either.
87
+
88
+ **Literal braces.** Every `{{` in a template starts a tag, and there is no escape for it. A `}}`
89
+ outside a tag is plain text. Producers keep `{{` out of template text (section 12).
90
+
91
+ **Sections nest.** Each `{{/name}}` closes the innermost open section, and its name must match
92
+ exactly: otherwise it is `mismatched-close`, or `unexpected-close` when nothing is open. Every
93
+ section must be closed (`unclosed-section`).
94
+
95
+ **Whole-template validation.** A runtime parses and validates the entire template before
96
+ rendering anything. A syntax error inside a section that would be skipped is still an error.
97
+
98
+ ## 5. Standalone lines
99
+
100
+ This is the same rule as Mustache's. It lets templates for the plain-text part put section tags on
101
+ their own lines without leaving blank lines behind.
102
+
103
+ A **line** ends after `\n`. `\r\n` counts as one line ending. The last line may have no ending. A
104
+ section, inverted or closing tag is **standalone** when its line holds only:
105
+ 1. optional spaces and tabs,
106
+ 2. that one tag,
107
+ 3. optional spaces and tabs,
108
+ 4. the line ending, or the end of the template.
109
+
110
+ The whole line is removed, including the spaces, the tabs and the line ending.
111
+
112
+ - Variables are never standalone.
113
+ - Two tags on one line are not standalone.
114
+ - Standalone removal happens while parsing, so it's the same whatever the data is.
115
+
116
+ ## 6. Name resolution
117
+
118
+ To resolve a name against the context stack:
119
+
120
+ 1. **`.`** is the innermost context.
121
+ 2. **The first segment:** search the contexts from the innermost outwards. Skip any context that
122
+ isn't an object. Stop at the first object that **has the key**, even if its value is `null`.
123
+ If no context has it, the result is nothing.
124
+ 3. **Each later segment** is looked up only in the value found so far. If that value isn't an
125
+ object or doesn't have the key, the result is nothing. The search never goes back to outer
126
+ contexts (Mustache's "broken chain" rule).
127
+
128
+ ## 7. Sections and truthiness
129
+
130
+ A value is **falsy** when it is nothing, `false`, `0` (including `-0`), `""` or `[]`. Everything
131
+ else is truthy, including `{}`, `"0"` and `" "`.
132
+
133
+ | Value of `name` | `{{#name}}…{{/name}}` | `{{^name}}…{{/name}}` |
134
+ |---|---|---|
135
+ | falsy | renders nothing | renders the block once, context unchanged |
136
+ | non-empty array | renders the block once per item, each item pushed as the context | nothing |
137
+ | `true` | renders the block once, **context unchanged** | nothing |
138
+ | object, non-empty string, non-zero number | renders the block once with the value pushed | nothing |
139
+
140
+ Tags inside a block that isn't rendered are never evaluated, so they raise no render errors.
141
+ Inside a section over a list of strings, `{{.}}` is the item. Inside `{{#flag}}`, `{{.}}` is
142
+ still the enclosing context.
143
+
144
+ ## 8. Variables
145
+
146
+ `{{name}}` and `{{{name}}}` resolve the name (section 6) and turn the value into text:
147
+
148
+ | Value | Text |
149
+ |---|---|
150
+ | string | the string, unchanged: no trimming, no Unicode normalisation, no line-ending conversion |
151
+ | number | the ECMAScript `Number::toString(x)` format (ECMA-262), radix 10 |
152
+ | `true` / `false` | `true` / `false` |
153
+ | nothing | error `missing-value` |
154
+ | array or object | error `non-scalar-value` |
155
+
156
+ The number format is the shortest decimal string that converts back to the same double:
157
+
158
+ | Value | Text | Rule |
159
+ |---|---|---|
160
+ | `42`, `-7`, `100.0` | `42`, `-7`, `100` | integers have no fraction or exponent |
161
+ | `-0` | `0` | negative zero has no sign |
162
+ | `0.1`, `0.30000000000000004` | same | shortest round-trip digits |
163
+ | `1e20` | `100000000000000000000` | decimal while the exponent is below 21 |
164
+ | `1e21`, `1.7976931348623157e308` | `1e+21`, `1.7976931348623157e+308` | exponent from `1e21`, with `+` |
165
+ | `0.000001`, `2.5e-5` | `0.000001`, `0.000025` | decimal down to `1e-6` |
166
+ | `1e-7`, `5e-324` | `1e-7`, `5e-324` | exponent below `1e-6`, no leading zeros |
167
+
168
+ - **JS:** `String(x)`.
169
+ - **Python:** `repr(float)` gives the same digits but a different layout (`1e-07`, `1e+20`,
170
+ `100.0`), so the runtime reformats them.
171
+ - **Go:** `strconv.FormatFloat(x, 'g', -1, 64)` gives the same digits, also with layout fixes.
172
+
173
+ Templates should rarely print raw numbers anyway, because values that depend on the locale arrive
174
+ already formatted as strings
175
+ ([ADR 0008](https://github.com/email-kit/email-kit/blob/main/docs/adr/0008-backend-formats-values.md)).
176
+
177
+ ## 9. Escaping profiles
178
+
179
+ Each template part is rendered with one profile:
180
+
181
+ | Part | Profile |
182
+ |---|---|
183
+ | HTML part | `html` |
184
+ | plain-text part, subject, preheader | `text` |
185
+
186
+ **`html` profile.** Values from `{{name}}` are escaped with exactly this table, in text and
187
+ attribute contexts alike. No other character is changed.
188
+
189
+ | Character | Becomes |
190
+ |---|---|
191
+ | `&` | `&amp;` |
192
+ | `<` | `&lt;` |
193
+ | `>` | `&gt;` |
194
+ | `"` | `&quot;` |
195
+ | `'` | `&#39;` |
196
+
197
+ **`text` profile.** Values are inserted unchanged.
198
+
199
+ **Both profiles:**
200
+ - `{{{name}}}` is never escaped.
201
+ - Template text is never escaped.
202
+ - Values are never parsed as templates, so a value of `{{secret}}` prints as `{{secret}}`.
203
+
204
+ Rules that depend on where a value is used are not part of the dialect. They belong to the
205
+ compiler and the generated module:
206
+ - which fields may appear in `href` and `src`;
207
+ - rejecting CR and LF in the subject.
208
+
209
+ A runtime API should treat an unknown profile as `html`, so a mistake fails safe.
210
+
211
+ ## 10. Errors
212
+
213
+ Every runtime uses these codes. Messages are free text; the conformance suite checks only the code.
214
+
215
+ | Code | When | Kind |
216
+ |---|---|---|
217
+ | `unclosed-tag` | `{{` without `}}`, or `{{{` without `}}}` | syntax |
218
+ | `unsupported-tag` | a comment, partial, set-delimiter, `&`, `<` or `$` tag | syntax |
219
+ | `invalid-name` | the tag content isn't a valid name (section 4) | syntax |
220
+ | `unclosed-section` | the template ends inside a section | syntax |
221
+ | `unexpected-close` | `{{/name}}` with no open section | syntax |
222
+ | `mismatched-close` | `{{/name}}` doesn't match the innermost open section | syntax |
223
+ | `missing-value` | a variable resolves to nothing | render |
224
+ | `non-scalar-value` | a variable resolves to an array or object | render |
225
+ | `invalid-number` | a variable or section resolves to NaN or an infinity | render |
226
+
227
+ - **Syntax errors** are raised before any output, for the whole template.
228
+ - **Render errors** stop the render. No partial output is returned.
229
+
230
+ ## 11. Conformance suite
231
+
232
+ The suite lives at [`conformance/mustache-core/`](https://github.com/email-kit/email-kit/blob/main/conformance/mustache-core/README.md). Each
233
+ file follows [`case-file.schema.json`](https://github.com/email-kit/email-kit/blob/main/conformance/mustache-core/case-file.schema.json) and
234
+ groups cases by topic. Each case gives:
235
+ - the profile,
236
+ - the template,
237
+ - the data,
238
+ - either `expected` (the exact output) or `error` (a code from section 10).
239
+
240
+ A runtime conforms to `mustache-core@1` when it passes every case in every file.
241
+
242
+ The suite has 142 cases. It will grow to at least 200, adding very long (10 KB) values and cases
243
+ from the Mustache spec.
244
+
245
+ ## 12. What producers guarantee
246
+
247
+ The email-kit compiler only writes templates that:
248
+
249
+ - **Parse without errors.** Every name is valid.
250
+ - **Contain no literal `{{`.** In HTML it writes `&#123;&#123;` instead. In the text part and the
251
+ subject, copy containing `{{` is a compile error.
252
+ - **Use `{{{ }}}` only behind the `<Raw>` allow-list**. Data is always escaped.
253
+ - **Reference only names the data schema defines**, so a `missing-value` error at send time means
254
+ the data didn't match the schema. Validating before rendering catches this earlier.
255
+
256
+ ## 13. Compatibility with stock engines
257
+
258
+ Backends may render compiled templates with their own Mustache or Handlebars engine.
259
+ These are the known differences; they haven't yet been verified by running the suite against
260
+ those engines.
261
+
262
+ | Engine | Difference |
263
+ |---|---|
264
+ | mustache.js | Also escapes `/`, `` ` `` and `=`. Renders missing values as empty strings. `0` is falsy, as here |
265
+ | Mustache spec engines (Ruby, Java, Python ports) | Renders missing values as empty strings. Some treat `0` and `""` as truthy. Numbers print the language's own way (`1.0`, `1e-07`) |
266
+ | Handlebars | Also escapes `=` and `` ` ``, and writes `'` as `&#x27;`. Doesn't search outer contexts unless `compat: true`. `0` is falsy. Missing values render as empty strings unless `strict: true` |
267
+
268
+ For output that is identical byte for byte, use an email-kit runtime.
269
+
270
+ ## 14. Design decisions
271
+
272
+ | Decision | Choice | Why |
273
+ |---|---|---|
274
+ | Base syntax | A strict subset of Mustache, standalone lines included | Mustache has a formal spec and an engine in every language. Keeping the standalone rule means stock engines lay out the plain-text part the same way |
275
+ | Name lookup | Mustache's context-stack search | Required for stock-engine compatibility. The compiler emits names that resolve the intended way |
276
+ | Falsy values | nothing, `false`, `0`, `""`, `[]` | Matches mustache.js and Handlebars, and how JS and Python authors read optional fields. Mustache leaves this to each language, so it has to be fixed here |
277
+ | `true` in a section | Context unchanged | Matches mustache.js |
278
+ | Missing variable | Error | A silent blank in a sent email is worse than a failed send |
279
+ | Booleans as text | `true` / `false` | Every language can produce them. Printing one is usually a template bug, but not an ambiguous one |
280
+ | Numbers as text | ECMAScript `Number::toString` | One exact, documented algorithm, native in the TS runtime and reproducible elsewhere |
281
+ | `'` escape | `&#39;` | What mustache.js writes; decimal is understood by every HTML parser, including old email clients |
282
+ | Escaped characters | Only `& < > " '` | Enough for HTML text and quoted attributes. A smaller table is easier to match exactly in every language |
283
+ | Not supported | Comments, partials, delimiters, `&`, lambdas | Templates carry no code and are never composed at runtime, and less for each runtime to implement |
284
+
285
+ ## 15. Data preparation in generated modules
286
+
287
+ mustache-core itself has no logic. A generated module's `render(data, { locale })` prepares the
288
+ data before filling the templates
289
+ ([ADR 0003](https://github.com/email-kit/email-kit/blob/main/docs/adr/0003-runtime-plurals.md)). A runtime in another language must produce
290
+ the same prepared data, byte for byte in what the templates can see.
291
+
292
+ 1. **Project** the data onto the schema's model: unknown keys go; a missing optional key becomes
293
+ `null`.
294
+ 2. **Prepare** every object, depth first. For an object, start from a copy of its parent's
295
+ entries (empty at the root), then for each of its fields, through nested objects but not into
296
+ lists:
297
+ - a number field: `plural.<path>` = `{ <category>: true }`, with the category from the
298
+ locale's CLDR rules (the CLDR version is in the manifest as `cldr`), plus
299
+ `exact_<n>: true` when the value is a non-negative safe integer;
300
+ - a string field with an `enum`: `select.<path>` = `{ <key>: true }`, where the key is `v_`
301
+ followed by the value with every character outside `A–Z a–z 0–9` written as `_<hex code
302
+ point>_` (`pro-plus` → `v_pro_2d_plus`).
303
+ If any entries result, set the object's `_ek` to `{ plural, select }`. An object's own entries
304
+ replace its parent's of the same name, the same way a field shadows an outer one in name
305
+ resolution (§6). Lists are prepared item by item, each item inheriting the list owner's entries.
306
+ 3. **Add the context** at the root: `_ek.context` holds the values passed to `createEmails()`.
307
+
308
+ `_ek` is reserved: schemas can't declare it, and projection drops it from the data.
309
+
310
+ Templates read these keys with sections. A message `{count, plural, =0 {…} one {…} other {…}}`
311
+ compiles to `{{#_ek.plural.count.exact_0}}…{{/…}}`, then the category sections inside inverted
312
+ sections of the exact matches; a `select` compiles to a section per case and the `other` case
313
+ inside inverted sections of the others. In a list item, `_ek` resolves to the item's own entry,
314
+ which is why every object inherits its parents' entries.
315
+
316
+ A CLDR category function takes a double `n` and uses the operands of UTS #35 computed from its
317
+ shortest round-trip decimal form: `i` the integer part, `v` and `f` the fraction digits and their
318
+ value, `w` and `t` the same without trailing zeros, `c` and `e` zero.
319
+
320
+ ## 16. Locale resolution in generated modules
321
+
322
+ `render(data, { locale })` picks one of the compiled locales for the requested BCP 47 tag:
323
+ RFC 4647 lookup, honouring CLDR's parent locales. The generated module embeds the
324
+ data, from the CLDR version in the manifest, filtered to the project's languages: `parents`
325
+ (a lowercase tag → the next tag; `und` means the root), `scripts` (a language → its likely
326
+ script) and `regions` (`language-region` → the script it implies, when that differs from the
327
+ language's). Explicit `locales.fallback` entries are written into `parents`, over CLDR's.
328
+
329
+ 1. **Key** a tag by lowercasing it, turning `_` into `-`, and, when its second subtag is a
330
+ region rather than a script, inserting the script `regions` gives (`zh-TW` → `zh-hant-tw`).
331
+ Compiled locales are keyed the same way.
332
+ 2. **Look up** the requested key among the compiled keys. A match returns that compiled locale.
333
+ 3. **Step** to `parents[key]` if there is one; otherwise drop the last subtag, and any
334
+ single-character subtag (`x`, `u`) left at the end. Dropping a script that isn't the
335
+ language's likely one to reach the bare language (`sr-latn` → `sr`) ends the lookup, as does
336
+ reaching `und` or `root`, or running out of subtags. Otherwise go to 2.
337
+ 4. **Default:** the first compiled locale.
338
+
339
+ Examples, with CLDR 47: `es-AR` → `es-419` → `es`; `pt-AO` → `pt-PT` → `pt`; `en-AU` →
340
+ `en-001` → `en`; `zh-TW` → `zh-Hant-TW` → `zh-Hant` → root, never `zh` (Simplified).
@@ -0,0 +1,326 @@
1
+ ---
2
+ name: email-kit
3
+ description: Write, change, translate, check and send emails with email-kit, where each email is a TSX template that `email-kit compile` turns into a typed module the backend calls as `emails.<id>.render(data)`. Use when asked to add or edit an email (welcome, password reset, magic link, one-time code, receipt, notification…), its copy or languages, its data or sample data, the email theme, to fix an `email-kit compile` or `email-kit check` error, or to write the backend code that renders and sends an email, in a project with an `email-kit.config.ts`.
4
+ license: MIT
5
+ ---
6
+
7
+ # email-kit
8
+
9
+ email-kit compiles emails written in TSX into one typed module that the server imports. Each email
10
+ is a folder with a `template.tsx` (its data schema, sample data and body) and a
11
+ `messages.<locale>.json` per language (every word it shows). `email-kit compile` writes the module;
12
+ the backend calls `render()` with data and passes the subject, HTML and text to its mail provider.
13
+ `email-kit check` finds problems with accessibility, dark mode, size, links, copy and translations.
14
+
15
+ Templates run when you **compile**, not when you send. So `data.name` in a template isn't a value
16
+ but a placeholder that `render()` fills later. Most mistakes come from forgetting this. Read
17
+ [Rules](#rules) before you write a template.
18
+
19
+ ## Find the project
20
+
21
+ 1. Find `email-kit.config.ts`. It's in the app that sends email (in a monorepo, such as
22
+ `apps/api`). Run every `email-kit` command in that folder.
23
+ 2. Read the config. `root` is the email-kit folder (default `src/email-kit`, or `email-kit` without
24
+ a `src/` folder). `locales.list` names every language. `sender` holds values such as
25
+ `productName`. `importPath` is how the app imports the emails, such as `@/email-kit`.
26
+ 3. Look at an existing template in the folder and follow its style.
27
+
28
+ ```
29
+ email-kit.config.ts
30
+ src/email-kit/
31
+ index.ts re-exports ./_generated: what the app imports
32
+ order-shipped/ one folder per email, named by its id
33
+ template.tsx
34
+ messages.en.json
35
+ messages.de.json
36
+ _shared/ your own components; folders starting with _ aren't templates
37
+ _generated/ compiled output: never edit it
38
+ ```
39
+
40
+ Run the CLI with the project's runner: `npx email-kit …`, `pnpm exec email-kit …`,
41
+ `yarn email-kit …` or `bunx email-kit …`. `init` also adds the scripts `email-kit:compile`,
42
+ `email-kit:watch` and `email-kit:check`.
43
+
44
+ ## Add an email
45
+
46
+ 1. **Create it:** `npx email-kit new password-reset`. Ids are lowercase words joined by hyphens.
47
+ This writes `password-reset/template.tsx` and a `messages.<locale>.json` for every locale, and
48
+ the email becomes `emails.passwordReset` after the next compile.
49
+ 2. **Describe the data** in `schema`: only what the email shows, already computed and formatted by
50
+ the backend. See [Schemas](#schemas).
51
+ 3. **Add fixtures:** named sample data that matches the schema, at least one. Add one per case that
52
+ changes the email (an optional field left out, a count of one).
53
+ 4. **Write the body** with components from `@email-kit/components` and `If`, `Unless` and `Each`
54
+ from `@email-kit/core`. No `<html>`, `<head>` or page container: the compiler adds them.
55
+ 5. **Write the copy** in `messages.<locale>.json`, with every key in every locale's file. Use
56
+ `t("key", { params })` in the template.
57
+ 6. **Compile:** `npx email-kit compile`. Fix each error by its id in brackets, such as
58
+ `[placeholder-misuse]`, using [the error reference](https://email-kit.dev/reference/errors).
59
+ 7. **Check:** `npx email-kit check`. Fix every error (`✗`, exit code 1). Fix warnings (`!`) unless
60
+ the user decides otherwise. Notes (`i`) are advice. Each finding names its check, explained in
61
+ [the check reference](https://email-kit.dev/reference/checks).
62
+ 8. **Send it** from the backend: see [Render and send](#render-and-send).
63
+
64
+ To change an email, edit its folder, then compile and check again. After changing a message file
65
+ or the config, compile too: `_generated/messages.d.ts` types `t()` from the default locale's
66
+ messages.
67
+
68
+ ## Example
69
+
70
+ `src/email-kit/password-reset/template.tsx`:
71
+
72
+ ```tsx
73
+ /** @jsxImportSource @email-kit/core */
74
+ import { Button, Footer, Heading, Text } from "@email-kit/components"
75
+ import { defineEmail, If, secretUrl } from "@email-kit/core"
76
+ import { z } from "zod"
77
+
78
+ export default defineEmail({
79
+ id: "password-reset",
80
+ purpose: "transactional",
81
+ schema: z.object({
82
+ name: z.string().min(1),
83
+ resetUrl: z.string().meta(secretUrl),
84
+ expiresInMinutes: z.number().int().min(1),
85
+ requestedFrom: z.string().min(1).optional(),
86
+ }),
87
+ subject: (_data, t, sender) => t("subject", { product: sender.productName }),
88
+ preheader: (data, t) => t("preheader", { minutes: data.expiresInMinutes }),
89
+ fixtures: {
90
+ default: {
91
+ name: "Ada",
92
+ resetUrl: "https://example.com/reset/abc123",
93
+ expiresInMinutes: 30,
94
+ requestedFrom: "Firefox on Windows",
95
+ },
96
+ "no-device": { name: "Ada", resetUrl: "https://example.com/reset/abc123", expiresInMinutes: 1 },
97
+ },
98
+ component: ({ data, t, sender }) => (
99
+ <>
100
+ <Heading>{t("heading", { name: data.name })}</Heading>
101
+ <Text>{t("intro", { minutes: data.expiresInMinutes })}</Text>
102
+ <If when={data.requestedFrom}>
103
+ {(device) => <Text tone="muted">{t("device", { device })}</Text>}
104
+ </If>
105
+ <Button href={data.resetUrl}>{t("cta")}</Button>
106
+ <Text size="bodySm" tone="muted">{t("ignore")}</Text>
107
+ <Footer reason={t("footer", { product: sender.productName })} sender={sender.productName} />
108
+ </>
109
+ ),
110
+ })
111
+ ```
112
+
113
+ `src/email-kit/password-reset/messages.en.json`:
114
+
115
+ ```json
116
+ {
117
+ "subject": "Reset your {product} password",
118
+ "preheader": "The link works for {minutes, plural, one {# minute} other {# minutes}}",
119
+ "heading": "Reset your password, {name}",
120
+ "intro": "Choose a new password with the button below. The link expires in {minutes, plural, one {# minute} other {# minutes}}.",
121
+ "device": "The request came from {device}.",
122
+ "cta": "Choose a new password",
123
+ "ignore": "If you didn't ask for this, ignore this email: your password stays the same.",
124
+ "footer": "You're receiving this email because someone asked to reset the password of your {product} account."
125
+ }
126
+ ```
127
+
128
+ The backend:
129
+
130
+ ```ts
131
+ import { emails } from "@/email-kit"
132
+
133
+ const { subject, html, text } = emails.passwordReset.render(
134
+ { name: user.name, resetUrl, expiresInMinutes: 30, requestedFrom: deviceLabel },
135
+ { locale: user.locale },
136
+ )
137
+ await sendMail({ to: user.email, subject, html, text })
138
+ ```
139
+
140
+ ## Rules
141
+
142
+ The compiler and `check` enforce these. Each one names the error or check id it's reported as.
143
+
144
+ ### Data is a placeholder
145
+
146
+ - **No computing with data.** Arithmetic, string methods, template literals, `.map()` and
147
+ spreading on a `data` field fail with `placeholder-misuse`. The backend computes the value and
148
+ passes it as a field of its own: `itemCount` rather than counting `data.items`, `fullName`
149
+ rather than joining two fields.
150
+ - **Conditions on data use `If`, `Unless` and `Each`** from `@email-kit/core`. Never use `&&`,
151
+ `? :`, comparisons or `if` on a `data` field: plain JavaScript runs once, at compile time, when
152
+ there's no value yet.
153
+ - `<If when={data.field}>`: an optional or nullable field (not a list), or a boolean. A function
154
+ child gets the field as a required value: `{(v) => <Text>{t("k", { v })}</Text>}`.
155
+ - `<Unless when={data.field}>`: when it's missing, `false` or an empty list.
156
+ - `<Each of={data.items}>{(item) => …}</Each>`: once per item. `If` refuses a list
157
+ (`list-condition`). For a heading that shows only with items, make the list part of an optional
158
+ object and wrap that object in `If`.
159
+ - "Missing" means `undefined`, `null`, `false`, `0`, `""` and `[]`. An optional number that may be
160
+ 0 needs a boolean of its own if 0 should show.
161
+ - **Plain JavaScript only for values known at compile time,** such as a constant or `locale`. `If`
162
+ on one fails with `static-condition`.
163
+ - **`style` values are fixed.** Choose between two fixed styles with `If`/`Unless`
164
+ (`data-dependent-style`).
165
+
166
+ ### Copy lives in messages
167
+
168
+ - Every word an email shows comes from `t(key, params)`, including the subject, the preheader,
169
+ button labels, alt text and footer lines. Don't write literal text in the template.
170
+ - Every locale in `locales.list` needs a `messages.<locale>.json` with every key
171
+ (`missing-message`). `t()` must pass exactly the parameters the message uses
172
+ (`missing-message-param`, `unused-message-param`).
173
+ - Messages are flat ICU: plain `{name}`, `plural` and `select` only.
174
+ - Plural: `{count, plural, one {# item} other {# items}}`. Give every category the locale uses,
175
+ and no others: English and German use `one` and `other`. Use `=0` for exactly zero, never
176
+ `zero` in English. `other` is required (`invalid-plural`).
177
+ - Select: `{plan, select, free {Free} pro {Pro} other {Standard}}`, on an enum field only, with
178
+ `other` (`invalid-select`).
179
+ - `{x, number}`, `{d, date}` and `{t, time}` fail with `unsupported-message`. So does a currency
180
+ symbol next to an argument (`i18n.intl-format`).
181
+ - Write `'{'` for a literal brace. An apostrophe on its own, as in "You're", needs no quoting.
182
+
183
+ ### Schemas
184
+
185
+ - Zod 4, Valibot or ArkType 2: use the library the project already uses. Valibot needs
186
+ `@valibot/to-json-schema` installed.
187
+ - Only a portable subset (`schema-not-portable`): strings (or enums), numbers, integers, booleans,
188
+ arrays and objects, each optional or nullable. No unions, records, tuples, `Date`, `bigint`,
189
+ `any`, defaults or transforms. Field names use letters, digits and `_` only.
190
+ - **Dates, money and numbers arrive formatted, as strings,** marked
191
+ `z.string().meta(formatted("money"))`. Kinds: `date`, `time`, `date-time`, `money`, `number`,
192
+ `percent`. The backend formats with the recipient's locale and time zone
193
+ ([Formatting](https://email-kit.dev/guide/formatting)). Plural counts are the exception: pass a
194
+ number.
195
+ - **Markers**, from `@email-kit/core`:
196
+ - `url` on every field used in `href` or `src` (`link.url-fields`). `render()` accepts only
197
+ `https://` values.
198
+ - `secret` on codes and tokens. They must stay out of the subject and preheader
199
+ (`subject.no-secret`).
200
+ - `secretUrl` on links that carry a token, such as reset and magic links.
201
+ - With Valibot: `v.pipe(v.string(), v.metadata(url))`. With ArkType: `type.string.configure(url)`.
202
+ - **Set limits.** `.min(1)` on required strings, and `.max(n)` on lists. `check` also renders an
203
+ empty variant ("Thanks, !" is reported by `copy.placeholder-fallbacks`), a long variant (25
204
+ items per list unless `maxItems` says fewer, which can exceed Gmail's clipping size, `size.gmail`)
205
+ and a hostile one.
206
+ - Fixtures must match the schema (`invalid-fixture`).
207
+
208
+ ### The template
209
+
210
+ - `id` equals the folder's name (`id-mismatch`). Never rename an id that has shipped: backends call
211
+ it by name.
212
+ - `purpose` is `"transactional"`, `"marketing"` or `"consent-request"`. Marketing and
213
+ consent-request emails must show a postal address (`legal.postal-address`), such as
214
+ `address={sender.postalAddress}` on `Footer`.
215
+ - End with `<Footer reason={…} sender={…} />`. Every email needs a reason line and a sender
216
+ (`legal.reason`, `legal.sender-identity`).
217
+ - Start the file with `/** @jsxImportSource @email-kit/core */`, unless the tsconfig sets
218
+ `"jsxImportSource": "@email-kit/core"`. Follow what the project's other templates do
219
+ (`source.jsx-pragma`).
220
+ - Exactly one `<Heading>` at level 1, then 2 and 3 without skipping a level (`a11y.one-h1`).
221
+ - One primary `Button`. Others use `variant="secondary"`. Button labels start with a verb. Link text
222
+ says where the link goes, never "click here" (`a11y.link-text`).
223
+ - No literal colours, font families or font sizes (`source.no-literal-colour`,
224
+ `source.no-font-family`, `source.no-font-size`). Use components, and theme roles such as
225
+ `role("muted")` in your own components ([Theme](https://email-kit.dev/guide/theme)).
226
+ - A literal URL starts with `https://`, `mailto:` or `tel:`. Images take an absolute `https:` URL
227
+ to a PNG, JPEG or GIF, a `kind`, a `width`, and `alt` unless they're decorative.
228
+ - `sender.<key>` reads the config's `sender`: `productName`, `name`, `legalName`,
229
+ `postalAddress`, `privacyUrl`, `helpUrl`, `supportEmail` or `siteUrl`. Reading a key the config
230
+ doesn't set fails with `sender-value-missing`: add it to the config or ask the user for the value.
231
+ - Your own components go in a `_`-prefixed folder such as `_shared/`, imported with a relative
232
+ path ([Components](https://email-kit.dev/guide/components#your-own-components)).
233
+
234
+ ### Never
235
+
236
+ - Never edit `_generated/` or anything in the config's `out`. Change the source and compile.
237
+ - Never turn a check off, or lower its level, to make `check` pass, unless the user agrees. A check
238
+ setting needs a `reason`:
239
+ `checks: { "id": { level: "off", reason: "…" } }`.
240
+ - Never format dates or amounts in a template or message. Never add a mail provider SDK the project
241
+ doesn't already use. Ask which one to use.
242
+
243
+ ## Components
244
+
245
+ From `@email-kit/components`. Props and examples are in
246
+ [Components](https://email-kit.dev/guide/components).
247
+
248
+ | Component | For |
249
+ |---|---|
250
+ | `Text` | A paragraph. `size`: `lead`, `body`, `bodySm`, `caption`. `tone`: `default`, `muted`, `subtle` |
251
+ | `Heading` | `level` 1 to 3 |
252
+ | `Link` | A text link: `href` |
253
+ | `Button` | A call to action: `href`, `variant` (`primary`, `secondary`, `destructive`), `size`, `fullWidth` |
254
+ | `Image` | `kind` (`decorative`, `informative`, `functional`), `src`, `width`, `height`, `alt`; `href` for `functional` |
255
+ | `Divider`, `Spacer` | A rule; vertical space |
256
+ | `Section` | A padded block: `surface` (`canvas`, `card`, `muted`), `padding` |
257
+ | `List`, `ListItem` | A bulleted list, or numbered with `ordered`, with `Each` for data |
258
+ | `KeyValue` | Labelled facts: `items={[{ label, value, copyable }]}` |
259
+ | `Callout` | A notice: `tone` (`info`, `success`, `warning`, `error`) and a required `title` |
260
+ | `OtpCode` | A one-time code: `label`, `code` (mark the field `secret`) |
261
+ | `DataTable` | Rows from a list field, with at least two `columns` |
262
+ | `LineItems` | Receipt and invoice lines with subtotal, discounts, shipping, taxes and total |
263
+ | `Footer` | `reason` and `sender` (required), `address`, `links` |
264
+
265
+ ## Render and send
266
+
267
+ Import from the config's `importPath`:
268
+
269
+ ```ts
270
+ import { EmailRenderError, emails } from "@/email-kit"
271
+
272
+ const { subject, html, text, meta } = emails.orderShipped.render(data, { locale: "de-AT" })
273
+ // meta.locale is the compiled locale used ("de"); without `locale`, the default
274
+ ```
275
+
276
+ - `render()` validates the data, picks the closest compiled locale and returns `subject`, `html`
277
+ and `text`. Send `html` and `text` together with `subject`. The preheader is already in both.
278
+ - The data type is `OrderShippedData` (one per template), exported from the module. A `formatted`
279
+ field's comment says how to format it.
280
+ - Bad data throws `EmailRenderError` with `code: "invalid-data"` and `issues: [{ path, message }]`.
281
+ `emails.<id>.validate(data)` returns the issues without rendering, for data from a queue or
282
+ webhook.
283
+ - If the config has a sender value `{ runtime: true }`, the module exports `createEmails({ … })`
284
+ instead of `emails`. Call it once at startup with the values (such as `siteUrl`) and reuse the
285
+ result.
286
+ - `@email-kit/runtime` must be in `dependencies`, not `devDependencies`
287
+ (`output.runtime-dependency`). The other `@email-kit/*` packages are devDependencies.
288
+ - Commit `_generated/`: `check` fails when it's out of date (`output.drift`). To compile in the
289
+ build instead, see [Checks and CI](https://email-kit.dev/guide/checks-and-ci).
290
+ - email-kit doesn't send mail. Pass the parts to whatever the project already uses, such as
291
+ Nodemailer, Resend, Postmark or SES. Examples are in
292
+ [Sending](https://email-kit.dev/guide/sending).
293
+ - A backend in another language uses `contract: true` and a mustache-core renderer
294
+ ([mustache-core](https://email-kit.dev/reference/mustache-core)).
295
+
296
+ ## Other tasks
297
+
298
+ | Task | How |
299
+ |---|---|
300
+ | Add a language | Add it to `locales.list` in the config, add `messages.<locale>.json` with every key to each template folder, then compile. Tags are canonical BCP 47: `pt-BR`, not `pt_br` ([Messages](https://email-kit.dev/guide/messages)) |
301
+ | Change colours or type | The config's `theme`, such as `theme: { source: "app/globals.css" }` for a shadcn theme. `npx email-kit tokens` prints the roles and their contrast ([Theme](https://email-kit.dev/guide/theme)) |
302
+ | Run checks in CI | `npx email-kit check --reporter github` after a full install ([Checks and CI](https://email-kit.dev/guide/checks-and-ci)) |
303
+ | Set up email-kit | `npm create email-kit` in the app that sends email ([Getting started](https://email-kit.dev/guide/getting-started)) |
304
+ | Update this skill | `npx email-kit agents` writes the skill for the installed version |
305
+
306
+ ## References
307
+
308
+ Read the page the task needs. Each is a page of the documentation at https://email-kit.dev, which
309
+ describes the latest version; https://email-kit.dev/llms-full.txt has all of it in one file. When
310
+ the project has email-kit installed, the same pages for its version are in
311
+ `node_modules/@email-kit/cli/dist/docs/`, such as `reference/errors.md`: read those instead.
312
+
313
+ | Page | What's in it |
314
+ |---|---|
315
+ | [Templates](https://email-kit.dev/guide/templates) | `defineEmail`, schemas, markers, fixtures, control flow, sender values |
316
+ | [Components](https://email-kit.dev/guide/components) | Every component's props, and writing your own |
317
+ | [Messages](https://email-kit.dev/guide/messages) | `t()`, plurals, selects, locales, fallback, pseudo-locales |
318
+ | [Theme](https://email-kit.dev/guide/theme) | Theme sources, colour roles, type scale, dark mode |
319
+ | [Checks and CI](https://email-kit.dev/guide/checks-and-ci) | Running `check`, levels, team checks, CI |
320
+ | [Sending](https://email-kit.dev/guide/sending) | The generated module, validation, locales, errors, sending |
321
+ | [Formatting](https://email-kit.dev/guide/formatting) | Formatting dates, money and numbers in JS, Python and Go |
322
+ | [CLI](https://email-kit.dev/reference/cli) | Every command and flag |
323
+ | [Configuration](https://email-kit.dev/reference/configuration) | Every config option |
324
+ | [Checks](https://email-kit.dev/reference/checks) | Every check, its default level and fix |
325
+ | [Errors](https://email-kit.dev/reference/errors) | Every error id, its cause and fix |
326
+ | [mustache-core](https://email-kit.dev/reference/mustache-core) | The placeholder language of the compiled output |