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

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## v1.0.0-beta.2
+
+### Added
+
+- Added `@lupinum/nuxt-email/build` to compile the existing typed email
+  registry for Node runtimes outside Nitro.
+- Added `@lupinum/nuxt-email/render` so compiled templates reuse the same
+  deterministic renderer, metadata, plain-text generation, and email-safe
+  components as Nuxt applications.
+
+### Production boundaries
+
+- Keep delivery, retries, idempotency, provider credentials, and audit state
+  application-owned. The package compiles and renders email; it does not send.
+- Reject source directories outside the application root, refuse to replace
+  output not owned by Nuxt Email, and preserve the last valid registry when a
+  build fails.
+- Exclude preview fixtures and source templates from the generated production
+  registry.
+
+## v1.0.0-beta.1
+
+Status: published on npm's `next` tag. Feature development is frozen until stable `1.0.0`. The three-client beta smoke test passed; the full eight-client checklist and external transactional beta remain pending.
+
+### Added
+
+- Added synchronous `subject` and authored plain-text `text` metadata to `defineEmail`, including prop-derived functions. Authored text takes precedence over automatic HTML-to-text derivation.
+- Added the type-only `EmailComponentProps<Component>` helper for deterministic, component-checked preview fixtures.
+- Added a baseURL-aware Nuxt DevTools shortcut to the existing development-only `/__email` preview.
+- Added direct Resend and local Nodemailer/Mailpit sending recipes while keeping all delivery behavior application-owned.
+
+### Changed
+
+- Rebuilt Tailwind v4 nested-selector and nested `@media`/`@supports` handling so declarations and rules preserve source order, media ranges are downleveled, and unhandled nesting fails instead of emitting raw `&` CSS.
+- Limited emitted keyframes to animations referenced by the current render. Animation remains best-effort progressive enhancement because email-client support is limited.
+- Made `EHtml.lang` a required, non-empty value. `dir` still defaults to `ltr`.
+- Made `ELink` visually neutral by removing its built-in color and underline. `target="_blank"` remains the default and can be overridden.
+- Renamed `EmailRenderError.componentName` to `templateName` and kept the original error as `cause`.
+- Limited module-driven registry rebuilds to structural template and fixture changes; ordinary edits continue through Nitro's normal watcher.
+
+### Breaking changes from v0.1.1
+
+- Every `EHtml` now requires an explicit non-empty `lang`.
+- `ELink` no longer supplies color or text-decoration styles. Add those styles explicitly where required.
+- Read `EmailRenderError.templateName` instead of `componentName`; there is no compatibility alias.
+- `defineEmail` rejects an empty object and invalid or asynchronous metadata values. Provide at least one synchronous `subject` or `text` value.
+
 ## v0.1.1
 
 [Compare changes](https://github.com/lupinum-dev/nuxt-email/compare/e45025a...v0.1.1)

package/README.md

@@ -1,19 +1,31 @@
 <p align="center">
-  <img src="docs/public/favicon.svg" width="128" alt="Nuxt Email icon">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/public/icon-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/public/icon-light.svg">
+    <img src="docs/public/icon-light.svg" width="128" alt="Nuxt Email icon">
+  </picture>
 </p>
 
-<h1 align="center">Nuxt Email</h1>
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/public/wordmark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/public/wordmark-light.svg">
+    <img src="docs/public/wordmark-light.svg" width="256" alt="Nuxt Email">
+  </picture>
+</h1>
 
 <p align="center">Write typed transactional email as Vue components and render it directly in Nuxt.</p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@lupinum/nuxt-email"><img src="https://img.shields.io/npm/v/@lupinum/nuxt-email?label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@lupinum/nuxt-email"><img src="https://img.shields.io/npm/v/@lupinum/nuxt-email?color=00DC82" alt="npm version"></a>
   <a href="https://github.com/lupinum-dev/nuxt-email/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/nuxt-email/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-00DC82" alt="MIT license"></a>
+  <a href="https://discord.gg/RPH6SeA36N"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord" alt="Discord"></a>
+  <a href="https://deepwiki.com/lupinum-dev/nuxt-email"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
 > [!WARNING]
-> The first scoped release is in preparation. Public APIs can change before version 1.0. The unscoped `nuxt-email` package on npm is unrelated to this project.
+> [`1.0.0-beta.2`](https://www.npmjs.com/package/@lupinum/nuxt-email/v/1.0.0-beta.2) is published on npm's `next` tag. The [three-client beta smoke test](https://github.com/lupinum-dev/nuxt-email/blob/main/docs/release/client-qa-checklist.md#100-beta1-smoke-test) passed against beta.1; the full eight-client checklist and an external transactional beta still block stable `1.0.0`. The unscoped `nuxt-email` package on npm is unrelated to this project.
 
 ## Why use Nuxt Email?
 
@@ -40,7 +52,7 @@ CI tests every supported Node major. The release consumer installs Nuxt `4.5.2`
 Install and register the module:
 
 ```bash
-pnpm add @lupinum/nuxt-email
+pnpm add @lupinum/nuxt-email@next
 ```
 
 ```ts
@@ -57,19 +69,30 @@ Create `app/emails/welcome.vue`:
 <script setup lang="ts">
 import { defineEmail } from '@lupinum/nuxt-email/define-email'
 
-const props = defineProps<{ firstName: string; activationUrl: string }>()
+const props = defineProps<{
+  firstName: string
+  activationUrl: string
+}>()
 
-defineEmail({ subject: () => `Welcome, ${props.firstName}` })
+defineEmail({
+  subject: () => `Welcome aboard, ${props.firstName}`,
+})
 </script>
 
 <template>
   <ETailwind>
     <EHtml lang="en">
-      <EBody class="bg-slate-100 p-6">
+      <EHead>
+        <title>Activate your account</title>
+      </EHead>
+      <EBody class="m-0 bg-slate-100 p-6">
         <EPreview>Your account is ready.</EPreview>
-        <EContainer class="bg-white p-6">
-          <EHeading>Welcome, {{ firstName }}</EHeading>
-          <EButton :href="activationUrl">Activate account</EButton>
+        <EContainer class="rounded-lg bg-white p-6">
+          <EHeading class="m-0 text-2xl text-slate-900">Welcome, {{ firstName }}</EHeading>
+          <EText class="text-slate-600">Finish setting up your account.</EText>
+          <EButton class="rounded-md bg-blue-600 px-5 py-3 text-white" :href="activationUrl">
+            Activate account
+          </EButton>
         </EContainer>
       </EBody>
     </EHtml>
@@ -88,7 +111,22 @@ export default defineEventHandler(async () => {
 })
 ```
 
-The template name and props are generated from the Vue file. Invalid names and props fail during type checking.
+The template name and props are generated from the Vue file. Invalid names and props fail during type checking. Use a sibling fixture to inspect it in `/__email`, then [pass the rendered result to your provider](https://nuxt-email.lupinum.com/docs/guides/sending-email).
+
+## Discord
+
+Join the Lupinum OSS community to discuss Nuxt Email, ask questions, and share
+what you build.
+
+<p align="center">
+  <a href="https://discord.gg/RPH6SeA36N">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/public/discord-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="docs/public/discord-light.svg">
+      <img src="docs/public/discord-light.svg" width="500" alt="Join the Lupinum OSS Discord">
+    </picture>
+  </a>
+</p>
 
 ## Email components
 
@@ -114,6 +152,16 @@ Run the Nuxt application and open `/__email`. The development-only page shows th
 
 Add one sibling fixture file for deterministic sample props. Preview routes and fixtures are excluded from production builds.
 
+```ts
+import type { EmailComponentProps } from '@lupinum/nuxt-email'
+import type WelcomeEmail from './welcome.vue'
+
+export default {
+  firstName: 'Ada',
+  activationUrl: 'https://example.com/activate',
+} satisfies EmailComponentProps<typeof WelcomeEmail>
+```
+
 ## Testing
 
 Render a Vue email without starting Nuxt:
@@ -138,14 +186,11 @@ Complete the [manual client QA checklist](https://github.com/lupinum-dev/nuxt-em
 
 ## Package exports
 
-- `@lupinum/nuxt-email` provides the Nuxt module and the `RenderedEmail` type.
-- `@lupinum/nuxt-email/define-email` provides typed template metadata.
-- `@lupinum/nuxt-email/testing` provides standalone component rendering.
-- `@lupinum/nuxt-email/errors` provides supported runtime error classes.
+The package has a module entry point plus focused build, production rendering, metadata, testing, and error subpaths. Use `@lupinum/nuxt-email/build` to compile a server registry and `@lupinum/nuxt-email/render` for compiled components outside Nitro. The [standalone guide](https://nuxt-email.lupinum.com/docs/guides/standalone-rendering) explains the build and runtime boundaries. The [canonical entry-point table](https://nuxt-email.lupinum.com/docs/reference/module#package-entry-points) lists every runtime and type-only export.
 
 ## Documentation
 
-Read the [Nuxt Email documentation](https://nuxt-email.lupinum.com/docs). It contains the [installation guide](https://nuxt-email.lupinum.com/docs/getting-started/installation), [component reference](https://nuxt-email.lupinum.com/docs/components), [testing guide](https://nuxt-email.lupinum.com/docs/guides/testing-your-emails), and [preview guide](https://nuxt-email.lupinum.com/docs/guides/preview-workflow).
+Read the [Nuxt Email documentation](https://nuxt-email.lupinum.com/docs). Start with the [installation guide](https://nuxt-email.lupinum.com/docs/getting-started/installation) and [component reference](https://nuxt-email.lupinum.com/docs/components). Use the guides for [preview](https://nuxt-email.lupinum.com/docs/guides/preview-workflow), [testing](https://nuxt-email.lupinum.com/docs/guides/testing-your-emails), and [sending](https://nuxt-email.lupinum.com/docs/guides/sending-email).
 
 See the [changelog](CHANGELOG.md) for released changes.
 

package/dist/build.d.mts

@@ -0,0 +1,13 @@
+interface BuildEmailRegistryOptions {
+    /** Application/project root, without loading its Nuxt configuration. */
+    rootDir: string;
+    /** Template directory relative to rootDir. Defaults to app/emails. */
+    templatesDir?: string;
+    /** Dedicated directory inside rootDir. Must be absent or previously created by this helper. */
+    outDir: string;
+}
+/** Compile trusted application templates. Never call this from a request or action. */
+declare function buildEmailRegistry(options: BuildEmailRegistryOptions): Promise<void>;
+
+export { buildEmailRegistry };
+export type { BuildEmailRegistryOptions };

package/dist/build.mjs

@@ -0,0 +1,218 @@
+import { execFile } from 'node:child_process';
+import { readFile, lstat, mkdir, mkdtemp, writeFile, rm, readdir, rename } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { relative, dirname, resolve, isAbsolute, join } from 'node:path';
+import { promisify } from 'node:util';
+import { build } from 'esbuild';
+import ts from 'typescript';
+import { d as discoverEmailTemplates, g as generateEmailRegistry, a as generateEmailTypes } from './shared/nuxt-email.B5ux0eBv.mjs';
+import { createHash } from 'node:crypto';
+import { parse, compileScript, compileTemplate } from 'vue/compiler-sfc';
+import '@nuxt/kit';
+
+function emailTemplatesPlugin(directory) {
+  return {
+    name: "nuxt-email-templates",
+    setup(build) {
+      build.onLoad({ filter: /\.vue$/ }, async ({ path }) => {
+        const { descriptor, errors } = parse(await readFile(path, "utf8"), { filename: path });
+        if (errors.length > 0) throw errors[0];
+        if (descriptor.styles.length || descriptor.customBlocks.length) {
+          throw new Error("Standalone email templates do not support style or custom blocks. Use ETailwind or inline styles.");
+        }
+        if ([descriptor.script, descriptor.scriptSetup, descriptor.template].some((block) => block?.src)) {
+          throw new Error("Standalone email templates do not support external SFC blocks. Import local components instead.");
+        }
+        if ([descriptor.script, descriptor.scriptSetup].some((block) => block?.lang && !["js", "ts"].includes(block.lang)) || descriptor.template?.lang && descriptor.template.lang !== "html") {
+          throw new Error("Standalone email templates support JavaScript/TypeScript scripts and HTML templates only.");
+        }
+        const id = createHash("sha256").update(relative(directory, path).replaceAll("\\", "/")).digest("hex").slice(0, 8);
+        const script = descriptor.script || descriptor.scriptSetup ? compileScript(descriptor, { id, genDefaultAs: "__emailComponent", inlineTemplate: false, isProd: true }) : void 0;
+        const template = descriptor.template ? compileTemplate({
+          source: descriptor.template.content,
+          filename: path,
+          id,
+          isProd: true,
+          compilerOptions: { bindingMetadata: script?.bindings },
+          transformAssetUrls: false
+        }) : void 0;
+        if (template?.errors.length) throw template.errors[0];
+        return {
+          contents: [
+            script?.content ?? "const __emailComponent = {}",
+            template?.code ?? "",
+            template ? "__emailComponent.render = render" : "",
+            "export default __emailComponent"
+          ].join("\n"),
+          loader: "ts",
+          resolveDir: dirname(path)
+        };
+      });
+    }
+  };
+}
+
+const execute = promisify(execFile);
+const require$1 = createRequire(import.meta.url);
+const renderImport = "@lupinum/nuxt-email/render";
+const ownershipMarker = ".nuxt-email-generated";
+const ownershipContent = "Generated by @lupinum/nuxt-email/build. Do not edit.\n";
+function contains(parent, child) {
+  const path = relative(parent, child);
+  return path === "" || !path.startsWith(`..`) && !isAbsolute(path);
+}
+async function replaceOutputDirectory(staging, outDir, replaceOutput) {
+  const previousRoot = await mkdtemp(join(dirname(outDir), ".nuxt-email-previous-"));
+  const previous = join(previousRoot, "output");
+  let removePreviousRoot = true;
+  try {
+    if (replaceOutput) await rename(outDir, previous);
+    try {
+      await rename(staging, outDir);
+    } catch (error) {
+      if (replaceOutput) {
+        try {
+          await rename(previous, outDir);
+        } catch (restoreError) {
+          removePreviousRoot = false;
+          throw new AggregateError(
+            [error, restoreError],
+            `Failed to replace generated email output and restore it. The prior output remains at ${previous}.`,
+            { cause: restoreError }
+          );
+        }
+      }
+      throw error;
+    }
+  } finally {
+    if (removePreviousRoot) await rm(previousRoot, { recursive: true, force: true });
+  }
+}
+async function normalizeDeclarationImports(directory) {
+  for (const file of await readdir(directory, { recursive: true })) {
+    if (!/\.d\.[cm]?ts$/.test(file)) continue;
+    const path = join(directory, file);
+    const source = ts.createSourceFile(path, await readFile(path, "utf8"), ts.ScriptTarget.Latest, true);
+    const transformed = ts.transform(source, [(context) => {
+      const visit = (node) => {
+        if (ts.isStringLiteral(node) && node.text.startsWith(".")) {
+          const parent = node.parent;
+          const isImport = ts.isImportDeclaration(parent) || ts.isExportDeclaration(parent) || ts.isLiteralTypeNode(parent) && ts.isImportTypeNode(parent.parent);
+          if (isImport && !node.text.endsWith(".json")) {
+            const module = ts.resolveModuleName(node.text, path, { moduleResolution: ts.ModuleResolutionKind.Bundler }, ts.sys).resolvedModule;
+            if (!module) throw new Error(`Cannot resolve emitted declaration import ${JSON.stringify(node.text)} from ${path}. Keep local imports inside the email directory.`);
+            const target = relative(dirname(path), module.resolvedFileName).replaceAll("\\", "/").replace(/\.d\.([cm]?)ts$/, ".$1js");
+            return ts.factory.createStringLiteral(target.startsWith(".") ? target : `./${target}`);
+          }
+        }
+        return ts.visitEachChild(node, visit, context);
+      };
+      return (node) => ts.visitNode(node, visit);
+    }]);
+    try {
+      await writeFile(path, ts.createPrinter().printFile(transformed.transformed[0]));
+    } finally {
+      transformed.dispose();
+    }
+  }
+}
+async function buildEmailRegistry(options) {
+  if (Object.keys(options).some((key) => key !== "rootDir" && key !== "outDir" && key !== "templatesDir")) {
+    throw new TypeError("buildEmailRegistry accepts only rootDir, outDir and templatesDir.");
+  }
+  const rootDir = resolve(options.rootDir);
+  const templatesDir = options.templatesDir ?? "app/emails";
+  if (isAbsolute(templatesDir)) throw new TypeError("templatesDir must be relative to rootDir.");
+  const directory = resolve(rootDir, templatesDir);
+  if (!contains(rootDir, directory)) throw new TypeError("templatesDir must remain inside rootDir.");
+  const outDir = resolve(rootDir, options.outDir);
+  if (!contains(rootDir, outDir)) throw new TypeError("outDir must remain inside rootDir so the generated module can resolve project dependencies.");
+  if (contains(directory, outDir) || contains(outDir, directory)) {
+    throw new TypeError("Generated output must be outside and must not contain the email directory.");
+  }
+  let replaceOutput = false;
+  try {
+    const output = await lstat(outDir);
+    if (!output.isDirectory() || output.isSymbolicLink()) throw new TypeError("outDir must be a generated directory, not a file or symlink.");
+    const marker = await readFile(join(outDir, ownershipMarker), "utf8").catch(() => "");
+    if (marker !== ownershipContent) throw new TypeError("Refusing to replace an outDir not owned by this build.");
+    replaceOutput = true;
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+  }
+  const templates = await discoverEmailTemplates(directory);
+  if (templates.length === 0) throw new TypeError("The email directory contains no templates.");
+  await mkdir(dirname(outDir), { recursive: true });
+  const staging = await mkdtemp(join(dirname(outDir), ".nuxt-email-build-"));
+  try {
+    const declarations = join(staging, "types");
+    const globals = join(staging, "components.d.ts");
+    await writeFile(globals, `import type { EmailComponents } from '${renderImport}'
+declare module 'vue' { interface GlobalComponents extends EmailComponents {} }
+export {}
+`);
+    const config = join(staging, "tsconfig.json");
+    await writeFile(config, JSON.stringify({
+      compilerOptions: {
+        target: "ES2022",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        strict: true,
+        skipLibCheck: true,
+        declaration: true,
+        emitDeclarationOnly: true,
+        noEmitOnError: true,
+        rootDir: directory,
+        declarationDir: declarations,
+        types: [],
+        lib: ["ES2022", "DOM", "DOM.Iterable"]
+      },
+      vueCompilerOptions: { strictTemplates: true },
+      files: [globals, ...templates.map((template) => template.sourcePath)]
+    }));
+    try {
+      await execute(process.execPath, [require$1.resolve("vue-tsc/bin/vue-tsc.js"), "-p", config], {
+        cwd: directory,
+        maxBuffer: 4 * 1024 * 1024
+      });
+    } catch (error) {
+      const diagnostics = error instanceof Error && "stdout" in error && typeof error.stdout === "string" ? error.stdout.trim() : "";
+      throw new Error(`Email declaration build failed${diagnostics ? `:
+${diagnostics}` : "."}`, { cause: error });
+    }
+    await normalizeDeclarationImports(declarations);
+    const registry = generateEmailRegistry(templates, {
+      emailRenderError: renderImport,
+      renderEmailComponent: renderImport,
+      templateRegistryErrors: renderImport
+    });
+    await build({
+      absWorkingDir: rootDir,
+      tsconfigRaw: { compilerOptions: { target: "ES2022", module: "ESNext" } },
+      stdin: { contents: registry, resolveDir: directory, sourcefile: "email-registry.js" },
+      outfile: join(staging, "index.mjs"),
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node22",
+      packages: "external",
+      logLevel: "silent",
+      plugins: [emailTemplatesPlugin(directory)]
+    });
+    await writeFile(join(staging, "index.d.mts"), generateEmailTypes(
+      templates.map((template) => ({
+        name: template.name,
+        sourcePath: `./types/${template.name}.vue.js`
+      })),
+      { renderedEmail: renderImport }
+    ));
+    await writeFile(join(staging, ownershipMarker), ownershipContent);
+    await rm(config);
+    await rm(globals);
+    await replaceOutputDirectory(staging, outDir, replaceOutput);
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+export { buildEmailRegistry };

package/dist/module.d.mts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-export { RenderedEmail } from '../dist/runtime/render/types.js';
+export { EmailComponentProps, RenderedEmail } from '../dist/runtime/render/types.js';
 
 interface CodeBlockOptions {
     languages: readonly string[];

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.5.1 <5"
   },
-  "version": "0.1.1",
+  "version": "1.0.0-beta.2",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"