Erste Schritte

Verso kompiliert ein Template zu einer JavaScript-Funktion. Es gibt keine Engine-Instanz, die man vorhalten muss, keinen View-Resolver zum Konfigurieren und nichts zu registrieren — Sie kompilieren eine Datei und rufen das Ergebnis auf.

Installation

Verso ist auf npm als verso veröffentlicht und unterstützt Node.js 18 und neuer. Es gibt keine optionalen Peer-Abhängigkeiten und keine Post-Install-Skripte.

$ npm install verso
$ pnpm add verso
$ yarn add verso

Das Paket bietet drei Einstiegspunkte:

Ihr erstes Template

Ein Template ist einfacher Text mit Interpolationen in doppelten geschweiften Klammern. Die Dateiendung ist üblicherweise .vs, aber nichts in der Bibliothek hängt davon ab.

<h1>{{title}}</h1>
<p>Signed in as {{user.name}}.</p>

Einmal kompilieren, dann beliebig oft aufrufen:

import { compileFile } from 'verso';

const hello = await compileFile('views/hello.vs');

hello({ title: 'Dashboard', user: { name: 'Ada' } });
// → '<h1>Dashboard</h1>\n<p>Signed in as Ada.</p>'

Der Rückgabewert ist eine gewöhnliche Funktion. Sie schließt nur über eine Handvoll Helfer-Referenzen, Sie können sie also serialisieren, auf der Platte cachen oder an einen Worker schicken.

Aus einem String kompilieren

Wenn das Template nicht aus dem Dateisystem kommt — eine Datenbankzeile, ein Request-Body, eine Test-Fixture —, verwenden Sie compile() und geben ihm einen Namen für Fehlermeldungen:

import { compile } from 'verso';

const row = compile('<td>{{value}}</td>', { name: 'row' });

Daten übergeben

Das erste Argument eines kompilierten Templates ist das Datenobjekt. Eigenschaften werden mit Optional-Chaining-Semantik nachgeschlagen: Ein fehlender Zwischenwert ergibt einen leeren String, statt eine Ausnahme zu werfen.

page({ user: null });   // {{user.name}} renders as ''
page({});               // same

Ein zweites Argument enthält Optionen zur Renderzeit — lokale Werte, die nicht zum Datenmodell gehören, etwa eine Request-ID oder eine Übersetzungsfunktion:

page(data, { locals: { t: translate, nonce: req.nonce } });

Im Template sind sie als {{@t('save')}} und {{@nonce}} erreichbar. Das Präfix @ hält sie sichtbar von Ihren Daten getrennt, was wichtiger ist, als es klingt, sobald Templates wachsen.

Streaming

Für Seiten, die aus mehreren langsamen Quellen bestehen, rendern Sie in einen Stream statt in einen String. Verso gibt jeden Block der obersten Ebene aus, sobald er fertig ist:

import { compileFile, renderToStream } from 'verso';

const page = await compileFile('views/report.vs');

server.get('/report', (req, res) => {
  res.type('html');
  renderToStream(page, { id: req.params.id }).pipe(res);
});

Mit {{#defer}} markierte Blöcke werden außer der Reihe fertig und von einem 400 Byte großen Inline-Skript an ihren Platz gesetzt. Ist JavaScript deaktiviert, erscheinen verzögerte Blöcke am Ende des Dokuments in Quellreihenfolge — eingeschränkt, aber vollständig.

Bundler und Build-Schritte

Vorkompilierte Templates halten den Parser aus Ihrem Produktions-Bundle heraus. Die CLI schreibt pro Template ein ES-Modul:

$ verso build views/ --out dist/views/ --format esm

Offizielle Plugins gibt es für Vite und esbuild, und beide sind etwa sechzig Zeilen lang — wenn Sie etwas anderes verwenden, ist es meist schneller, eines davon zu kopieren, als einen generischen Loader zu konfigurieren.

Wie es weitergeht

Die Syntax-Referenz behandelt Blöcke, Filter und Partials. Die API-Referenz dokumentiert jede exportierte Funktion und Option. Wenn Sie Verso in eine Build-Pipeline einbauen, ist die CLI-Referenz der kürzeste Weg.