Nuxt

examples/nuxt ist eine Nuxt-4-App, die den Editor einbettet und ihn über eigene Server-Routen anbindet. Sie speichert Templates und gespeicherte Blöcke als JSON-Dateien unter ./data, rendert HTML-Export und Test-E-Mails auf dem Server mit @templatical/renderer und mjml und schreibt jede Test-E-Mail nach ./data/outbox, statt sie zu versenden. CI baut die App und führt sie bei jeder Änderung am SDK in einem Browser aus.

Ausführen des Beispiels

Kopieren Sie es in ein neues Verzeichnis:

bash

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

Die Editor-Komponente

Eine reine Client-Komponente (.client.vue) bindet den Editor in onMounted ein und unmountet ihn in onBeforeUnmount – auch einen Editor, der erst fertig lädt, nachdem die Komponente entfernt wurde. Sie wartet zuerst einen Tick, weil Nuxt das Template einer reinen Client-Komponente erst nach dem Mounten der Komponente rendert. Sie importiert init() innerhalb von onMounted, daher läuft der Editor nie auf dem Server. Ohne ?id= in der URL legt sie ein Template an und schreibt dessen neue ID in die URL. Schlägt das Öffnen des Templates fehl, zeigt die Werkzeugleiste die Meldung des Servers an, etwa „Template not found.“, mit einem Link, der ein neues Template anlegt. Die Werkzeugleiste zeigt auch Fehler, die der Editor über onError meldet, etwa eine Bibliothek gespeicherter Blöcke, die nicht lädt, und einen fehlgeschlagenen Export; der nächste Export entfernt sie.

app/components/EmailEditor.client.vue

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>

Die Provider

Der Editor erreicht das Backend nur über diese Objekte. Jede Methode ist ein fetch an eine der Routen unten. Die Datei ist in den Beispielen für Next.js, Nuxt, SvelteKit und React Router identisch.

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,
};

Die Server-Routen

Nuxt bildet jede Datei unter server/api/ auf eine Route ab und die Methode in ihrem Namen (.get, .post, …) auf die HTTP-Methode. Jede Route prüft ihre Eingaben, ruft den Store oder den Renderer auf und antwortet mit JSON oder einem leeren 204. Eine abgelehnte Anfrage erhält einen 4xx-Status und { message }, die der Editor anzeigt.

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);
});

Die Render- und die Test-E-Mail-Route kompilieren das Template mit renderTemplate() aus 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 };
}

Wechsel in die Produktion

Ersetzen Sie die Funktionsrümpfe in server/utils/templatical/store.ts durch Aufrufe Ihrer Datenbank. Jede Route, die Templates oder gespeicherte Blöcke lädt oder speichert, nutzt diese Funktionen.
Ersetzen Sie deliver() in server/utils/templatical/outbox.ts durch Ihren E-Mail-Anbieter. Die Funktion erhält Empfänger, Betreff und das fertige HTML.
Sichern Sie die Server-Routen mit einer Authentifizierung ab. In diesem Beispiel sind sie offen.
Bereinigen Sie HTML-Blöcke auf dem Server, bevor Sie sie speichern oder versenden, oder übergeben Sie in render.ts allowHtmlBlocks: false an renderToMjml: Der Editor speichert Autoren-HTML unverändert.
Bevor Sie eine Cookie-basierte Authentifizierung hinzufügen, lehnen Sie Schreibzugriffe ohne content-type: application/json ab oder verwenden Sie CSRF-Tokens: Eine fremde Seite kann einen Body ohne content-type oder mit multipart/form-data ohne Preflight senden, und diese Routen lesen beide Varianten als JSON.

Backend anbinden behandelt die Provider, die dieses Beispiel auslässt: Versionsverlauf, Kommentare und Medien.

Nuxt ​

Ausführen des Beispiels ​

Die Editor-Komponente ​

Die Provider ​

Die Server-Routen ​

Wechsel in die Produktion ​