Nuxt

examples/nuxt is a Nuxt 4 app that embeds the editor and backs it with its own server routes. It stores templates and saved blocks as JSON files under ./data, renders HTML export and test emails on the server with @templatical/renderer and mjml, and writes each test email to ./data/outbox instead of sending it. CI builds the app and runs it in a browser against every change to the SDK.

Running the example

Copy it into a new directory:

npx degit templatical/sdk/examples/nuxt my-app
cd my-app
npm install
npm run dev

The editor component

A client-only component (.client.vue) mounts the editor in onMounted and unmounts it in onBeforeUnmount, including an editor that finishes loading after the component has gone. It waits one tick first, because Nuxt renders a client-only component's template after the component mounts. It imports init() inside onMounted, so the editor never runs on the server. Without ?id= in the URL, it creates a template and writes the new id into the URL. If opening the template fails, the toolbar shows the server's message, such as "Template not found.", with a link that starts a new template. The toolbar also shows errors the editor reports through onError, such as a saved-block library that fails to load, and a failed export; the next export clears them.

app/components/EmailEditor.client.vue

<script setup lang="ts">
import { nextTick, onBeforeUnmount, onMounted, ref } from "vue";
import type { TemplaticalEditor } from "@templatical/editor";
import "@templatical/editor/style.css";
import {
  renderProvider,
  savedBlocksProvider,
  templatesProvider,
  testEmailProvider,
} from "../utils/templatical/providers";

type Problem = { message: string; offerRestart: boolean };

// Every message ends as a sentence: the providers' fallback, such as
// "GET /api/templates/… failed (500)", has no full stop and would run into the
// restart link.
const messageOf = (error: unknown) => {
  const text = (error instanceof Error ? error.message : String(error)).trim();
  return /[.!?]$/.test(text) ? text : `${text}.`;
};

const container = ref<HTMLDivElement>();
const problem = ref<Problem | null>(null);
let editor: TemplaticalEditor | null = null;
let unmounted = false;

async function openEditor(el: HTMLDivElement) {
  // Imported here, not at the top: the editor runs only in the browser.
  const { init } = await import("@templatical/editor");
  if (unmounted) return;
  const instance = await init({
    container: el,
    templates: templatesProvider,
    savedBlocks: savedBlocksProvider,
    testEmail: testEmailProvider,
    render: renderProvider,
    onError: (error) => {
      if (!unmounted) problem.value = { message: messageOf(error), offerRestart: false };
    },
  });
  if (unmounted) {
    instance.unmount();
    return;
  }
  editor = instance;

  // ?id= picks the template; without one, create a template and put its id in
  // the URL so a reload reopens the same template.
  const id = new URLSearchParams(window.location.search).get("id");
  if (id) {
    await instance.load(id);
  } else {
    const template = await instance.create({ name: "Untitled" });
    if (!unmounted) window.history.replaceState(window.history.state, "", `?id=${template.id}`);
  }
}

onMounted(async () => {
  // Nuxt renders a .client.vue component's template one tick after the
  // component mounts, so the container does not exist until then.
  await nextTick();
  const el = container.value;
  if (!el) return;
  openEditor(el).catch((error: unknown) => {
    // The providers throw the server's own message, such as "Template not found."
    if (!unmounted) problem.value = { message: messageOf(error), offerRestart: true };
  });
});

onBeforeUnmount(() => {
  unmounted = true;
  editor?.unmount();
  editor = null;
});

async function exportHtml() {
  // A new export replaces an earlier failure. A failed load keeps its message
  // and restart link: the template it names never opened.
  if (!problem.value?.offerRestart) problem.value = null;
  // Opened inside the click, so a popup blocker allows it, and filled once
  // the HTML is ready.
  const tab = window.open("", "_blank");
  if (!tab) {
    problem.value = { message: "Allow pop-ups for this page to see the export.", offerRestart: false };
    return;
  }
  try {
    const html = await editor?.toHtml();
    if (!html) {
      tab.close();
      return;
    }
    // The HTML renders in a sandboxed frame: HTML blocks and rich text are
    // author content, and in this tab they would run with the app's origin.
    const frame = tab.document.createElement("iframe");
    frame.setAttribute("sandbox", "");
    frame.srcdoc = html;
    frame.style.cssText = "border: 0; width: 100%; height: 100%";
    tab.document.documentElement.style.height = "100%";
    tab.document.body.style.cssText = "margin: 0; height: 100%";
    tab.document.body.append(frame);
  } catch (error) {
    tab.close();
    problem.value = { message: messageOf(error), offerRestart: false };
  }
}
</script>

<template>
  <div class="toolbar">
    <button type="button" data-testid="export-html" @click="exportHtml">Export HTML</button>
    <span v-if="problem" role="alert">
      {{ problem.message }}
      <template v-if="problem.offerRestart"><a href="/">Start a new template</a>.</template>
    </span>
  </div>
  <div ref="container" class="editor" />
</template>

The providers

The editor reaches the backend only through these objects. Each method is one fetch to a route below. The file is the same in the Next.js, Nuxt, SvelteKit and React Router examples.

app/utils/templatical/providers.ts

// The editor reaches the backend only through these four objects. Each method
// is one fetch to an /api route of this app; point them at any backend that
// implements the same routes, in any language.
import type {
  RenderProvider,
  SavedBlocksListParams,
  SavedBlocksProvider,
  TemplatesProvider,
  TestEmailProvider,
} from "@templatical/types";

async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
  const response = await fetch(path, {
    method,
    // Every write declares JSON, the bodyless DELETE included: a framework's
    // CSRF check (SvelteKit's, for one) treats a write without a content type
    // as a form post and can reject it as cross-site.
    headers: method === "GET" ? undefined : { "content-type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  if (!response.ok) {
    const error = (await response.json().catch(() => null)) as { message?: string } | null;
    throw new Error(error?.message ?? `${method} ${path} failed (${response.status})`);
  }
  return (response.status === 204 ? undefined : await response.json()) as T;
}

function listQuery(params: SavedBlocksListParams = {}): string {
  const query = new URLSearchParams();
  if (params.search) query.set("search", params.search);
  if (params.category) query.set("category", params.category);
  const text = query.toString();
  return text ? `?${text}` : "";
}

export const templatesProvider: TemplatesProvider = {
  load: (id) => request("GET", `/api/templates/${encodeURIComponent(id)}`),
  create: (input) => request("POST", "/api/templates", input),
  save: (id, patch) => request("PATCH", `/api/templates/${encodeURIComponent(id)}`, patch),
  autoSave: true,
};

export const savedBlocksProvider: SavedBlocksProvider = {
  list: (params) => request("GET", `/api/saved-blocks${listQuery(params)}`),
  create: (input) => request("POST", "/api/saved-blocks", input),
  update: (id, patch) => request("PATCH", `/api/saved-blocks/${encodeURIComponent(id)}`, patch),
  delete: (id) => request("DELETE", `/api/saved-blocks/${encodeURIComponent(id)}`),
};

export const testEmailProvider: TestEmailProvider = {
  defaultRecipient: "[email protected]",
  send: ({ recipient, content }) => request("POST", "/api/test-email", { recipient, content }),
};

export const renderProvider: RenderProvider = {
  toMjml: async ({ content }) =>
    (await request<{ mjml: string }>("POST", "/api/render", { content })).mjml,
  toHtml: async ({ content }) =>
    (await request<{ html: string }>("POST", "/api/render", { content })).html,
};

The server routes

Nuxt maps each file under server/api/ to a route, and the method in its name (.get, .post, …) to the HTTP method. Each route validates its input, calls the store or the renderer, and answers with JSON or an empty 204. A rejected request gets a 4xx status and { message }, which the editor reports.

server/api/templates/index.post.ts

import { createTemplate, templateInputError, type TemplateInput } from "../../utils/templatical/store";

export default defineEventHandler(async (event) => {
  const body: unknown = await readBody(event).catch(() => null);
  const problem = templateInputError(body, false);
  if (problem) {
    setResponseStatus(event, 400);
    return { message: problem };
  }
  setResponseStatus(event, 201);
  return createTemplate(body as TemplateInput);
});

server/api/templates/[id].get.ts

import { getTemplate } from "../../utils/templatical/store";

export default defineEventHandler(async (event) => {
  const template = await getTemplate(getRouterParam(event, "id") ?? "");
  if (!template) {
    setResponseStatus(event, 404);
    return { message: "Template not found." };
  }
  return template;
});

server/api/templates/[id].patch.ts

import type { TemplatePatch } from "@templatical/types";
import { templateInputError, updateTemplate } from "../../utils/templatical/store";

export default defineEventHandler(async (event) => {
  const body: unknown = await readBody(event).catch(() => null);
  const problem = templateInputError(body, true);
  if (problem) {
    setResponseStatus(event, 400);
    return { message: problem };
  }
  const template = await updateTemplate(getRouterParam(event, "id") ?? "", body as TemplatePatch);
  if (!template) {
    setResponseStatus(event, 404);
    return { message: "Template not found." };
  }
  return template;
});

server/api/saved-blocks/index.get.ts

import { listSavedBlocks } from "../../utils/templatical/store";

export default defineEventHandler(async (event) => {
  const query = getQuery(event);
  return listSavedBlocks({
    search: typeof query.search === "string" ? query.search : undefined,
    category: typeof query.category === "string" ? query.category : undefined,
  });
});

server/api/saved-blocks/index.post.ts

import type { SavedBlockInput } from "@templatical/types";
import { createSavedBlock, savedBlockInputError } from "../../utils/templatical/store";

export default defineEventHandler(async (event) => {
  const body: unknown = await readBody(event).catch(() => null);
  const problem = savedBlockInputError(body, false);
  if (problem) {
    setResponseStatus(event, 400);
    return { message: problem };
  }
  setResponseStatus(event, 201);
  return createSavedBlock(body as SavedBlockInput);
});

server/api/saved-blocks/[id].patch.ts

import type { SavedBlockPatch } from "@templatical/types";
import { savedBlockInputError, updateSavedBlock } from "../../utils/templatical/store";

export default defineEventHandler(async (event) => {
  const body: unknown = await readBody(event).catch(() => null);
  const problem = savedBlockInputError(body, true);
  if (problem) {
    setResponseStatus(event, 400);
    return { message: problem };
  }
  const block = await updateSavedBlock(getRouterParam(event, "id") ?? "", body as SavedBlockPatch);
  if (!block) {
    setResponseStatus(event, 404);
    return { message: "Saved block not found." };
  }
  return block;
});

server/api/saved-blocks/[id].delete.ts

import { deleteSavedBlock } from "../../utils/templatical/store";

export default defineEventHandler(async (event) => {
  if (await deleteSavedBlock(getRouterParam(event, "id") ?? "")) return sendNoContent(event, 204);
  setResponseStatus(event, 404);
  return { message: "Saved block not found." };
});

server/api/render.post.ts

import { isRenderableTemplateContent } from "@templatical/types";
import { renderTemplate } from "../utils/templatical/render";

export default defineEventHandler(async (event) => {
  const body = (await readBody(event).catch(() => null)) as { content?: unknown } | null;
  if (!isRenderableTemplateContent(body?.content)) {
    setResponseStatus(event, 400);
    return { message: "`content` must be a template with a `blocks` array." };
  }
  return renderTemplate(body.content);
});

server/api/test-email.post.ts

import { isRenderableTemplateContent } from "@templatical/types";
import { deliver, isEmailAddress } from "../utils/templatical/outbox";
import { renderTemplate } from "../utils/templatical/render";

export default defineEventHandler(async (event) => {
  const body = (await readBody(event).catch(() => null)) as { recipient?: unknown; content?: unknown } | null;
  if (!isEmailAddress(body?.recipient)) {
    setResponseStatus(event, 400);
    return { message: "Enter a valid email address." };
  }
  if (!isRenderableTemplateContent(body.content)) {
    setResponseStatus(event, 400);
    return { message: "`content` must be a template with a `blocks` array." };
  }
  const { html } = await renderTemplate(body.content);
  await deliver({ to: body.recipient, subject: "Test email", html });
  return sendNoContent(event, 204);
});

The render and test-email routes compile the template with renderTemplate() from server/utils/templatical/render.ts:

// Compiles a template to email HTML on the server: the renderer turns the
// editor's JSON into MJML, and the mjml package turns MJML into HTML.
import mjml2html from "mjml";
import { renderToMjml } from "@templatical/renderer";
import type { TemplateContent } from "@templatical/types";

export async function renderTemplate(content: TemplateContent): Promise<{ mjml: string; html: string }> {
  const mjml = await renderToMjml(content);
  const { html } = await mjml2html(mjml);
  return { mjml, html };
}

Moving to production

• Replace the function bodies in server/utils/templatical/store.ts with calls to your database. Every route that loads or saves templates or saved blocks goes through them.
• Replace deliver() in server/utils/templatical/outbox.ts with your email provider. It receives the recipient, the subject and the finished HTML.
• Add authentication to the server routes. They are open in this example.
• Sanitize HTML blocks on the server before you store or send them, or pass allowHtmlBlocks: false to renderToMjml in render.ts: the editor keeps author HTML as written.
• Before you add cookie-based authentication, reject writes that don't send content-type: application/json, or add CSRF tokens: a cross-site page can send a body with no content-type, or with multipart/form-data, without a preflight, and these routes parse either as JSON.

Connect your backend covers the providers this example leaves out: version history, comments and media.