@lupinum/nuxt-email 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/agent/pages/docs/guides/testing-your-emails.md

@@ -0,0 +1,118 @@
+---
+title: "Testing your emails"
+description: "Render templates and assert on their output in unit tests with the @lupinum/nuxt-email/testing utilities."
+url: "https://nuxt-email.lupinum.com/docs/guides/testing-your-emails"
+route: "/docs/guides/testing-your-emails"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Testing your emails
+
+> Render templates and assert on their output in unit tests with the @lupinum/nuxt-email/testing utilities.
+
+Nuxt Email exposes a standalone renderer from `@lupinum/nuxt-email/testing`. It renders templates using the eighteen built-in components without booting a Nuxt app.
+
+```ts
+import { renderEmailComponent } from '@lupinum/nuxt-email/testing'
+```
+
+## renderEmailComponent
+
+Renders a Vue email component to `{ html, text, subject? }` — the same `RenderedEmail` shape [`renderEmail`](/raw/docs/reference/render-email.md) returns, produced by the same renderer.
+
+```ts [test/welcome.test.ts]
+import { renderEmailComponent } from '@lupinum/nuxt-email/testing'
+import Welcome from '../app/emails/welcome.vue'
+
+test('welcome renders the recipient name', async () => {
+  const { html, text } = await renderEmailComponent(Welcome, {
+    firstName: 'Ada',
+    activationUrl: 'https://example.com/activate',
+  })
+
+  expect(html).toContain('Welcome, Ada')
+  expect(text).toContain('Welcome, Ada')
+})
+```
+
+Because this test imports a Vue single-file component (`.vue` file) directly, enable Vue's Vite transform in the test project:
+
+```ts [vitest.config.ts]
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    environment: 'node',
+  },
+})
+```
+
+Install `vitest` and `@vitejs/plugin-vue` as direct development dependencies. The helper is Node-only; do not import it from application components, shared browser code, or client plugins.
+
+`renderEmailComponent` infers the second argument from the imported Vue component. Required props make it required, optional-only props make it optional, and prop-free components reject invented props. It returns `Promise<RenderedEmail>`. Because rendering is deterministic, the same component and props always produce the same output.
+
+## Testing configured components
+
+When a template uses an application-configured component such as `ECodeBlock`, resolve the aliases generated by `nuxt prepare` and import the generated renderer binding:
+
+```ts [vitest.config.ts]
+import vue from '@vitejs/plugin-vue'
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+const tsconfigPath = fileURLToPath(new URL('./.nuxt/tsconfig.json', import.meta.url))
+const tsconfig = JSON.parse(readFileSync(tsconfigPath, 'utf8'))
+const rendererPath = tsconfig.compilerOptions.paths['#nuxt-email/testing']?.[0]
+if (!rendererPath) throw new Error('Run `nuxt prepare` before configured email tests')
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '#nuxt-email/testing': resolve(dirname(tsconfigPath), rendererPath),
+    },
+  },
+  test: {
+    environment: 'node',
+  },
+})
+```
+
+Keep these configured-renderer tests under `test/nuxt/`, which Nuxt includes in that generated TypeScript project.
+
+```ts
+import { renderEmailComponent } from '#nuxt-email/testing'
+```
+
+Before running these tests:
+
+1. Install `vitest` and `@vitejs/plugin-vue`.
+2. Run `nuxt prepare` to generate the alias path.
+3. Keep configured-renderer tests under `test/nuxt/`.
+4. Import `#nuxt-email/testing` only from Node tests. Do not import it from application or shared client code.
+
+The alias reads Nuxt's generated path as its source of truth. The Vue plugin compiles the `.vue` file without starting a browser application. Nuxt unit tests disable server-side rendering (SSR), but email components are server-only. The generated binding and production `renderEmail` use the same complete component registry.
+
+The standalone package helper rejects unresolved `E*` components. It does not return fake custom-element markup in development or production.
+
+Prefer focused assertions on recipient-visible text, links, required attributes, and client-specific markup. Whole-document snapshots can approve accidental output. The React and Vue comparison normalizer remains internal because its rules belong to the conformance suite, not the public HTML contract.
+
+## Asserting on the subject
+
+If a template declares a subject with [`defineEmail`](/raw/docs/guides/subject-lines.md), `renderEmailComponent` computes it from the props you pass:
+
+```ts
+const { subject } = await renderEmailComponent(Welcome, { firstName: 'Ada', activationUrl: '…' })
+expect(subject).toBe('Welcome aboard, Ada')
+```
+
+## What testing does not replace
+
+Unit tests prove your template's structure and content are stable and deterministic. They do **not** prove how a real client renders the message. Pair them with the [manual client compatibility](/raw/docs/guides/client-compatibility.md) checklist before a release.

package/dist/agent/pages/docs/guides.md

@@ -0,0 +1,32 @@
+---
+title: "Guides"
+description: "Task-focused guides for authoring, previewing, testing, and sending transactional email."
+url: "https://nuxt-email.lupinum.com/docs/guides"
+route: "/docs/guides"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Guides
+
+> Task-focused guides for authoring, previewing, testing, and sending transactional email.
+
+These guides go beyond the per-component reference to cover common authoring tasks end to end.
+
+<cards cols="2">
+<card title="Preview workflow" description="Use /__email and inspect the exact HTML, text, and subject." icon="lucide:eye" to="/docs/guides/preview-workflow" />
+
+<card title="Sending email" description="Hand rendered HTML, text, and subject to a provider or local SMTP server." icon="lucide:send" to="/docs/guides/sending-email" />
+
+<card title="Using Tailwind" description="Inline utilities, nested-component support, and documented limitations." icon="lucide:paintbrush" to="/docs/guides/tailwind" />
+
+<card title="Subject lines" description="Compute a subject from props with defineEmail." icon="lucide:mail" to="/docs/guides/subject-lines" />
+
+<card title="Plain text" description="How the text fallback is produced and how to control it." icon="lucide:file-text" to="/docs/guides/plain-text" />
+
+<card title="Testing your emails" description="Render and assert with the scoped package testing utilities." icon="lucide:flask-conical" to="/docs/guides/testing-your-emails" />
+
+<card title="Client compatibility" description="The manual QA checklist and what is proven." icon="lucide:check-check" to="/docs/guides/client-compatibility" />
+</cards>

package/dist/agent/pages/docs/reference/conformance.md

@@ -0,0 +1,55 @@
+---
+title: "Conformance and divergences"
+description: "How compatibility is measured against React Email, the current pass numbers, and every intentional divergence."
+url: "https://nuxt-email.lupinum.com/docs/reference/conformance"
+route: "/docs/reference/conformance"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Conformance and divergences
+
+> How compatibility is measured against React Email, the current pass numbers, and every intentional divergence.
+
+Compatibility is reported **per behavior**. No global "React Email compatible" percentage is claimed. The generated repository report is the authoritative source; this page explains its method.
+
+## How it is measured
+
+The current Nuxt Email candidate is compared against **React Email `6.9.0`** and **`@react-email/render` `2.1.0`**. Each behavior is a case that renders the same input through both renderers and asserts one of these classifications:
+
+- **exact** — byte-identical output.
+- **normalized** — identical after the internal conformance helper canonicalizes insignificant serialization differences such as attribute order, trailing `style` semicolons, class whitespace, and self-closing form.
+- **semantic** — specific asserted properties match.
+- **intentional-divergence** — output differs on purpose, for a documented email-safety or Vue-authoring reason.
+- **unsupported** — a React Email component that is not ported.
+
+## Current results
+
+The generated repository report is the only source for current counts, classifications, fixed commits, and hashes. This page does not copy values that can drift. See the [generated conformance report](https://github.com/lupinum-dev/nuxt-email/blob/main/docs/conformance/report.md) and its [provenance record](https://github.com/lupinum-dev/nuxt-email/blob/main/docs/conformance/provenance.md).
+
+## Intentional divergences
+
+| Case | Reason |
+| --- | --- |
+| `html-defaults` | Vue SSR does not inject React 19's implicit empty head into a standalone `html` element. |
+| `preview-max-length` | `EPreview` omits React 19 title output and keeps its hiding and plain-text exclusion invariant, because Vue SSR cannot safely hoist title into head. |
+| `preview-short` | React 19 hoists Preview title into head; Vue authors place title explicitly in `EHead`. `EPreview` keeps hiding styles and `data-skip-in-text` fixed so user attributes cannot expose filler. |
+| `preview-style-override` | React replaces all hiding styles when a user style is provided; `EPreview` retains the hiding defaults as an email-safety invariant. |
+| `preview-unicode-boundary` | React truncates at 200 UTF-16 code units and can split a surrogate pair; `EPreview` drops the whole boundary code point and fills the remaining position. |
+| `row-columns` | `EColumn` omits React Email's internal `data-id` marker because no Vue behavior consumes it. |
+
+## Additional documented differences
+
+- **`EMarkdown` drops `data-id`.** React Email wraps Markdown in `<div data-id="react-email-markdown">`; `EMarkdown` omits the marker (the same no-data-id divergence as `EColumn`).
+- **Presentation tables reject fixed attributes.** `ESection`, `EContainer`, and `ERow` throw a `TypeError` when passed `border`, `cellpadding`, `cellspacing`, or `role`. React Email silently discards these overrides; Nuxt Email fails loudly to keep the email-safe table layout an invariant.
+- **`ECodeInline` excludes its compatibility copy from plain text.** HTML retains the hidden `Orange.fr` fallback span, but plain-text conversion skips it so recipients receive the code once. React Email emits it twice.
+- **`ETailwind` moves non-inlinable rules to `<head>`.** Media-query and pseudo-class rules move to a `<style>` in `<head>`. This needs a head inside `ETailwind`; rendering fails without one. Residual class names are sanitized. Outlook-specific (`mso-*`) properties survive inlining.
+- **`ETailwind` reaches classes inside nested components.** Style-bearing primitives resolve their classes during rendering. A second pass handles marked plain and structural elements without changing other output. Nested `ETailwind` boundaries are not supported. See the [Tailwind guide](/raw/docs/guides/tailwind.md).
+
+## Scope, not a parity guarantee
+
+The report records zero failing runnable cases and lists unsupported React components. Its runnable scope is the eighteen built-ins. It records opt-in `ECodeBlock` as an intentional difference from React Email's CodeBlock.
+
+This does not mean every React Email component or option has a Nuxt Email equivalent. Use the generated repository report as the authoritative matrix of cases, classifications, differences, and unsupported surface.

package/dist/agent/pages/docs/reference/define-email.md

@@ -0,0 +1,69 @@
+---
+title: "defineEmail"
+description: "Declare a template subject or authored plain-text alternative from script setup."
+url: "https://nuxt-email.lupinum.com/docs/reference/define-email"
+route: "/docs/reference/define-email"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# defineEmail
+
+> Declare a template subject or authored plain-text alternative from script setup.
+
+`defineEmail(options)` declares metadata for the current email render. Import it only in an email template.
+
+```vue [app/emails/welcome.vue]
+<script setup lang="ts">
+import { defineEmail } from '@lupinum/nuxt-email/define-email'
+
+const props = defineProps<{
+  firstName: string
+}>()
+
+defineEmail({
+  subject: () => `Welcome aboard, ${props.firstName}`,
+  text: () => `Welcome aboard, ${props.firstName}. Your account is ready.`,
+})
+</script>
+```
+
+## Signature
+
+```ts
+type EmailMetadataValue = string | (() => string)
+
+type DefineEmailOptions
+  = | { subject: EmailMetadataValue, text?: EmailMetadataValue }
+    | { subject?: EmailMetadataValue, text: EmailMetadataValue }
+
+function defineEmail(options: DefineEmailOptions): void
+```
+
+At least one of `subject` or `text` is required. Extra keys and other value types fail. Functions take no arguments, run synchronously after HTML rendering, and can close over the template's real `defineProps()` value. An asynchronous function is not supported.
+
+## Metadata precedence
+
+| Metadata | Result |
+| --- | --- |
+| `subject` declared | `RenderedEmail.subject` contains the resolved string. |
+| `subject` absent | `RenderedEmail.subject` is absent. No subject is derived. |
+| `text` declared | `RenderedEmail.text` contains the authored string. |
+| `text` absent | `RenderedEmail.text` is derived from the final HTML. |
+
+Call `defineEmail()` once per template render. It may run before or after a top-level `await` in `<script setup>`. Calling it outside an email render throws `DefineEmailOutsideRenderError`; calling it twice in one render throws `DuplicateEmailDefinitionError`.
+
+## Entry-point exports
+
+Import from `@lupinum/nuxt-email/define-email`:
+
+| Export | Kind |
+| --- | --- |
+| `defineEmail` | Runtime function |
+| `DefineEmailOutsideRenderError` | Runtime error class |
+| `DuplicateEmailDefinitionError` | Runtime error class |
+| `DefineEmailOptions` | Type only |
+
+See [subject and authored text](/raw/docs/guides/subject-lines.md) for task-oriented examples and [error types](/raw/docs/reference/errors.md) for recovery guidance.

package/dist/agent/pages/docs/reference/errors.md

@@ -0,0 +1,72 @@
+---
+title: "Error types"
+description: "Public error classes, their stable fields, common symptoms, and recovery steps."
+url: "https://nuxt-email.lupinum.com/docs/reference/errors"
+route: "/docs/reference/errors"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Error types
+
+> Public error classes, their stable fields, common symptoms, and recovery steps.
+
+Nuxt Email exposes five runtime error classes from `@lupinum/nuxt-email/errors`. Original render failures remain available through `cause`.
+
+## Public errors
+
+| Error | When it occurs | Stable fields | What to do |
+| --- | --- | --- | --- |
+| `EmailRenderError` | Loading, prop validation, Vue server rendering, document validation, or plain-text conversion fails. | `templateName`; original failure on `cause` | Log the error and inspect `cause`. Fix the template, props, or document named by `templateName`. |
+| `UnknownEmailTemplateError` | An untyped runtime name is absent from the generated registry. | `requestedName`; sorted `knownNames` | Use one of `knownNames`, or add the template and run `nuxt prepare`. |
+| `TailwindMissingHeadError` | A Tailwind media-query or pseudo-class rule has no `<head>` inside its `ETailwind` boundary. | Message names the affected classes. | Move `EHead` inside `ETailwind`, or remove the classes that require head CSS. |
+| `DefineEmailOutsideRenderError` | `defineEmail()` runs outside an email render. | Error identity and message | Call it from an email template rendered by Nuxt Email. |
+| `DuplicateEmailDefinitionError` | One render calls `defineEmail()` more than once. | Error identity and message | Keep one call and combine its `subject` and `text` metadata. |
+
+`EmailRenderError.templateName` is the registry name for `renderEmail()`. Standalone rendering uses the Vue component name. There is no `componentName` compatibility alias.
+
+## Find an error by symptom
+
+| Search phrase or symptom | Error | Next check |
+| --- | --- | --- |
+| Template not found, unknown template, or unknown email | `UnknownEmailTemplateError` | Compare `requestedName` with `knownNames`. Nested names use `/` and omit `.vue`. |
+| Missing head, `<head> not found`, or Tailwind variant failure | `TailwindMissingHeadError` | Confirm that `EHead` is inside the same `ETailwind` boundary. |
+| `defineEmail` outside render | `DefineEmailOutsideRenderError` | Keep the call in the template's `<script setup>`. |
+| Duplicate email definition | `DuplicateEmailDefinitionError` | Search the template and its setup path for a second call. |
+| Render failed, invalid document, or invalid props | `EmailRenderError` | Inspect `error.cause`; it preserves the underlying failure. |
+
+There is no `TemplateNotFoundError`. The public class for that condition is `UnknownEmailTemplateError`.
+
+## Imports
+
+```ts
+import {
+  DefineEmailOutsideRenderError,
+  DuplicateEmailDefinitionError,
+  EmailRenderError,
+  TailwindMissingHeadError,
+  UnknownEmailTemplateError,
+} from '@lupinum/nuxt-email/errors'
+```
+
+`EmailRenderError` is also exported by `@lupinum/nuxt-email/testing`. The two metadata errors are also exported by `@lupinum/nuxt-email/define-email`.
+
+Template discovery can report `DuplicateEmailTemplateError` or `EmailTemplateDiscoveryError` during module setup. These are diagnostics, not exports from the public error entry point.
+
+## Production handling
+
+Log the full error on the server, including `cause`. Return a generic response to the caller. Nuxt Email does not serialize filesystem paths or stacks into production responses. The [development preview](/raw/docs/guides/preview-workflow.md) shows richer local details for authoring.
+
+```ts [server/api/welcome.get.ts]
+export default defineEventHandler(async () => {
+  try {
+    return await renderEmail('welcome', props)
+  }
+  catch (error) {
+    console.error(error)
+    throw createError({ statusCode: 500, statusMessage: 'Email render failed' })
+  }
+})
+```

package/dist/agent/pages/docs/reference/migration.md

@@ -0,0 +1,144 @@
+---
+title: "Migration from React Email"
+description: "Translate JSX templates, props, and rendering calls to Nuxt Email's Vue single-file components and generated server API."
+url: "https://nuxt-email.lupinum.com/docs/reference/migration"
+route: "/docs/reference/migration"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Migration from React Email
+
+> Translate JSX templates, props, and rendering calls to Nuxt Email's Vue single-file components and generated server API.
+
+## Upgrade from 0.1.1
+
+`1.0.0-beta.1` makes four intentional hard cutovers:
+
+- Add a non-empty `lang` to every `EHtml`.
+- Style `ELink` color and text decoration explicitly when the design needs them; the component is now visually neutral.
+- Replace reads of `EmailRenderError.componentName` with `templateName`. No deprecated alias is provided.
+- Give `defineEmail` at least one synchronous `subject` or `text` value. Authored `text` now replaces derived plain text.
+
+For preview fixtures, replace the longer Vue utility-type expression with `EmailComponentProps<typeof YourEmail>`. Fixtures remain deterministic objects, not factories or scenarios.
+
+Nuxt Email ports proven email-output behavior, not React's runtime or component API. Move a template by preserving its semantic document, replacing React components with the E-prefixed Vue primitives, and exposing it through Nuxt's generated server registry.
+
+## The same email, two frameworks
+
+### React Email
+
+```tsx
+import { Body, Button, Container, Head, Heading, Html, Preview, Text } from '@react-email/components'
+
+export function OrderEmail({ orderNumber, recipientName }: { orderNumber: number; recipientName: string }) {
+  return (
+    <Html lang="en">
+      <Head><title>Order confirmation</title></Head>
+      <Preview>Your order is ready.</Preview>
+      <Body style={{ backgroundColor: '#f5f5f5', margin: 0 }}>
+        <Container style={{ maxWidth: '600px', padding: '24px' }}>
+          <Heading>Order {orderNumber} for {recipientName}</Heading>
+          <Text>We have received your order.</Text>
+          <Button href={`https://example.com/orders/${orderNumber}`} style={{ padding: '12px 20px' }}>
+            View order
+          </Button>
+        </Container>
+      </Body>
+    </Html>
+  )
+}
+```
+
+### Nuxt Email
+
+Place the Vue version at `app/emails/order-confirmation.vue`:
+
+```vue
+<script setup lang="ts">
+import { defineEmail } from '@lupinum/nuxt-email/define-email'
+
+const props = defineProps<{
+  orderNumber: number
+  recipientName: string
+}>()
+
+defineEmail({
+  subject: () => `Order ${props.orderNumber} confirmed`,
+})
+</script>
+
+<template>
+  <EHtml lang="en">
+    <EHead><title>Order confirmation</title></EHead>
+    <EBody :style="{ backgroundColor: '#f5f5f5', margin: 0 }">
+      <EPreview>Your order is ready.</EPreview>
+      <EContainer :style="{ maxWidth: '600px', padding: '24px' }">
+        <EHeading>Order {{ orderNumber }} for {{ recipientName }}</EHeading>
+        <EText>We have received your order.</EText>
+        <EButton :href="`https://example.com/orders/${orderNumber}`" :style="{ padding: '12px 20px' }">
+          View order
+        </EButton>
+      </EContainer>
+    </EBody>
+  </EHtml>
+</template>
+```
+
+`EPreview` belongs inside `EBody`, and the document title goes explicitly in `EHead` — Vue SSR does not reproduce React 19's preview-title hoisting (an [intentional divergence](/raw/docs/reference/conformance.md)).
+
+## Rendering
+
+React Email renders an element directly and requests HTML and plain text separately:
+
+```tsx
+const html = await render(<OrderEmail {...props} />)
+const text = await render(<OrderEmail {...props} />, { plainText: true })
+```
+
+Nuxt Email discovers the Vue single-file component (`.vue` file) as `order-confirmation`. It generates its prop type and returns both representations from one server renderer:
+
+```ts [server/api/order-confirmation.get.ts]
+export default defineEventHandler(() => {
+  return renderEmail('order-confirmation', {
+    orderNumber: 7319,
+    recipientName: 'Ada',
+  })
+})
+```
+
+Do not import a component renderer into application code. The public path is the generated Nitro-only [`renderEmail`](/raw/docs/reference/render-email.md) auto-import.
+
+## Authoring translation
+
+| React Email | Nuxt Email |
+| --- | --- |
+| JSX/TSX component | Vue `.vue` file under `app/emails/` |
+| Imported `Html`, `Body`, `Text`, `Button` | Auto-registered `EHtml`, `EBody`, `EText`, `EButton` |
+| TypeScript function props | Standard Vue `defineProps<>()` |
+| `children` | Default Vue slot |
+| `{condition && <Text />}` | `<EText v-if="condition">` |
+| `{items.map(item => <Text key={item.id} />)}` | `<EText v-for="item in items" :key="item.id">` |
+| `style={{ backgroundColor: '#fff' }}` | `:style="{ backgroundColor: '#fff' }"` |
+| `<Tailwind>` wrapper | Auto-registered [`ETailwind`](/raw/docs/components/tailwind.md) |
+| Renderer receives an element | Renderer receives a generated template name and typed props |
+| Preview-specific React app | Exact sibling fixture plus development-only `/__email` |
+
+Use Vue's native attribute names and CSS styles. React-shaped convenience props such as `mx` are intentionally absent — use ordinary CSS in `style`.
+
+`ETailwind` uses Tailwind v4, but it does not automatically inherit your Nuxt stylesheet or browser CSS variables. Pass concrete `theme`/`config` values from your application-owned token source when migrating custom utilities such as `text-primary`.
+
+## Behavioral differences to review
+
+- Compatibility is tracked **per behavior**, never as a global React Email compatibility claim.
+- Component names and the authoring API are Vue-native and E-prefixed.
+- React streaming, Suspense behavior, generated React markers, JSX execution, and the React preview stack are not ported.
+- Some document, preview, and table-marker output intentionally differs where Vue authoring or email safety requires it.
+
+Do not use this summary as a parity matrix — review the [conformance report](/raw/docs/reference/conformance.md) for the authoritative cases and divergences.
+
+## Sending remains application-owned
+
+Nuxt Email stops at `{ html, text, subject? }`. Keep recipients, sender identity, credentials, attachments, tags, scheduling, and delivery policy in your provider SDK. Nuxt Email has no provider-neutral adapter or public send endpoint. You can keep provider-specific features and optionally compute the subject beside the template with [`defineEmail`](/raw/docs/guides/subject-lines.md).

package/dist/agent/pages/docs/reference/module.md

@@ -0,0 +1,90 @@
+---
+title: "Module behavior"
+description: "What the module registers, its fixed conventions, and the opt-in codeBlock configuration."
+url: "https://nuxt-email.lupinum.com/docs/reference/module"
+route: "/docs/reference/module"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Module behavior
+
+> What the module registers, its fixed conventions, and the opt-in codeBlock configuration.
+
+Nuxt Email is a standard Nuxt module registered in `modules`. Discovery, preview routes, and the render API are fixed by convention. Syntax-highlighted blocks are the one opt-in feature.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-email'],
+})
+```
+
+## What the module registers
+
+- **Components.** Eighteen built-in `E*` components are auto-imported for use inside email templates. Configuring `codeBlock` adds `ECodeBlock`.
+- **`renderEmail`** — a Nitro-only auto-import generated from the discovered templates, typed with each template's name and props.
+- **`defineEmail` entry point** — import it from `@lupinum/nuxt-email/define-email` inside a template to declare [subject or authored text metadata](/raw/docs/reference/define-email.md).
+- **Development preview** — the `/__email` application and its endpoints, registered only when `nuxt.options.dev` is true.
+- **Nuxt DevTools shortcut** — a development-only iframe tab pointing to that same baseURL-aware preview.
+
+## Package entry points
+
+The published package exposes six entry points. Runtime and type-only exports are listed separately.
+
+| Import | Runtime exports | Type-only exports |
+| --- | --- | --- |
+| `@lupinum/nuxt-email` | Default Nuxt module | `ModuleOptions`, `RenderedEmail`, `EmailComponentProps` |
+| `@lupinum/nuxt-email/build` | `buildEmailRegistry` (Node build only) | `BuildEmailRegistryOptions` |
+| `@lupinum/nuxt-email/render` | `renderEmailComponent`, `EmailRenderError`, `UnknownEmailTemplateError` | `RenderedEmail`, `EmailComponentProps`, `EmailComponents` |
+| `@lupinum/nuxt-email/define-email` | `defineEmail`, `DefineEmailOutsideRenderError`, `DuplicateEmailDefinitionError` | `DefineEmailOptions` |
+| `@lupinum/nuxt-email/testing` | `renderEmailComponent`, `EmailRenderError` | `RenderedEmail` |
+| `@lupinum/nuxt-email/errors` | `EmailRenderError`, `UnknownEmailTemplateError`, `DefineEmailOutsideRenderError`, `DuplicateEmailDefinitionError`, `TailwindMissingHeadError` | — |
+
+After `nuxt prepare`, the generated `#nuxt-email/testing` alias supplies the configured testing renderer. Use it when a template depends on generated component configuration such as `ECodeBlock`. It follows the same `renderEmailComponent` and `EmailRenderError` testing surface.
+
+There is no public `renderEmail` package export; its type is generated from each application's templates.
+For a server registry without Nitro, see [Render outside Nitro](/raw/docs/guides/standalone-rendering.md).
+
+## Template discovery
+
+- Templates are `.vue` files under `app/emails/`.
+- Nested paths become slash-separated names (`app/emails/account/reset-password.vue` → `account/reset-password`).
+- `app/emails/components/` is reserved for your own supporting components and is not discovered.
+- Discovery follows the active Nuxt `srcDir`: a custom `srcDir: 'src/'` uses `src/emails/`.
+- Email templates from inherited Nuxt layers are not merged into the active application's registry. Keep the application-owned templates in its active `srcDir/emails` tree.
+- In a monorepo, register the module in each Nuxt application that sends email. Each application owns one registry from its own active `srcDir/emails`; package and layer templates are not merged implicitly.
+- Sibling `.fixtures.ts` files supply deterministic preview props in development and are excluded from production output.
+
+The registry is regenerated when templates are added, renamed, or deleted, which changes the generated server types. Run `nuxt prepare` after such changes.
+
+## Optional syntax highlighting
+
+`codeBlock` is the only module option. It uses the Shiki syntax highlighter. The option requires one theme and a non-empty, closed language allowlist:
+
+| Option | Type | Default | Required |
+| --- | --- | --- | --- |
+| `codeBlock` | `{ languages: readonly string[], theme: string }` | — | No |
+| `codeBlock.languages` | Non-empty `readonly string[]` | — | Yes when `codeBlock` is set |
+| `codeBlock.theme` | `string` | — | Yes when `codeBlock` is set |
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-email'],
+  nuxtEmail: {
+    codeBlock: {
+      languages: ['typescript', 'vue'],
+      theme: 'github-dark',
+    },
+  },
+})
+```
+
+Only the configured languages and the grammars they import enter the server bundle. Nuxt Email creates the highlighter on first use. Without this option, `ECodeBlock` is unregistered and Shiki performs no module-setup or production-bundle work. Shiki remains an installation-time dependency. Unsupported top-level options fail during setup.
+
+## Production boundary
+
+The production server keeps templates referenced by its registry because Nitro renders them there. The client bundle excludes those templates.
+
+The `/__email` application, its endpoints, and every discovered `.fixtures.ts` module are absent from production output. See the [preview workflow](/raw/docs/guides/preview-workflow.md) and [security boundary](/raw/docs/reference/render-email.md#security-boundary).