@samva/vite

The unified local editor for Samva email, SMS, and WhatsApp templates. One Vite plugin discovers .samva and .tsx files, evaluates TSX through the Samva JSX runtime, applies the project theme, and serves the full visual editor with HMR.

Install

Keep the authoring library and editor in the project, with Vite provided as the editor's peer:

npm install --save-dev @samva/markup @samva/vite vite

samva templates init writes these dependencies, an equivalent samva.vite.config.ts, and collision-resistant samva:dev / samva:push package scripts. Existing project scripts remain untouched.

import { samvaEditor } from "@samva/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [samvaEditor({ templatesDir: "emails" })],
});

Run vite and open http://localhost:5173/. The default assumes this dev server exists only for Samva authoring:

• editor UI: /
• editor API and event streams: /api/*
• bundled editor assets: /assets/*

To share a Vite server with another app, choose a route:

samvaEditor({ templatesDir: "emails", route: "/__samva" });

That mounts the UI at /__samva/, the API at /__samva/api/*, and the bundled assets at /__samva/assets/*. Requests outside the configured route pass through to the rest of the Vite middleware stack.

Authoring files

• .samva files are editable for every channel.
• .tsx files are code-authored and always read-only in the editor. The source view shows authored TSX beside the emitted SML used for rendering.
• A .tsx file contains at most one template, and that template must be its default export. Named exports are ignored, so they remain available for helpers and constants. A file without a default export is excluded with a warning; an invalid default export is a diagnostic.

import { Email, Text } from "@samva/markup/components";
import type { Variables } from "@samva/markup/variables";

export const subjectPrefix = "Hello"; // helper, ignored by discovery

export default function Welcome(v: Variables<{ firstName: string }>) {
  return (
    <Email>
      <Text>
        {subjectPrefix}, {v.firstName}
      </Text>
    </Email>
  );
}

The editor keeps preview, SML, compiled HTML/plain text or channel payload, light/dark email rendering, responsive widths, diagnostics, and variable samples in one surface. Editing a template, imported dependency, or theme.css refreshes the relevant catalog and open document.

Options

| Option | Type | Default | Description | | -------------- | ----------------- | ------------- | ---------------------------------------------------------------- | | templatesDir | string | "emails" | Recursive .samva / .tsx template directory. | | route | string | "/" | Absolute editor UI route; API and assets are mounted beneath it. | | theme | string \| false | "theme.css" | Project theme file, or false to disable discovery. | | compile | CompileOptions | — | Extra compile options applied to local rendering and validation. |

Theme and push

A root theme.css uses Tailwind v4 @theme syntax. Theme changes recompile local previews while preserving the last valid theme when an edit is temporarily invalid.

samva templates push --dir emails and buildTemplates() run the same default-export TSX evaluation and emit pipeline. They send or return SML, never compiled HTML; the platform recompiles the SML with the organization theme.

The runnable examples/email-starter workspace exercises this exact setup.

Template identity

Template identity comes from the file name, and only the default export is evaluated — welcome-email.tsx owns the platform slug welcome-email. Renaming a file changes template identity; the CLI treats the new name as a different template and --force does not remap identities. Direct @samva/vite/emit callers pass the file-backed template name:

emitModulePreview("welcome-email", moduleExports, compileOptions);