Pierwsze kroki

Verso kompiluje szablon do funkcji JavaScriptu. Nie ma instancji silnika do przechowywania, resolvera widoków do konfiguracji ani niczego do rejestrowania — kompilujesz plik i wywołujesz wynik.

Instalacja

Verso jest opublikowane w npm jako verso i obsługuje Node.js 18 i nowsze. Nie ma opcjonalnych zależności peer ani skryptów poinstalacyjnych.

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

Pakiet udostępnia trzy punkty wejścia:

Pierwszy szablon

Szablon to zwykły tekst z interpolacjami w podwójnych nawiasach klamrowych. Rozszerzenie to zwyczajowo .vs, ale nic w bibliotece od tego nie zależy.

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

Skompiluj raz, a potem wywołuj, ile chcesz:

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>'

Zwracana wartość to zwykła funkcja. Domyka się tylko nad garścią odwołań do funkcji pomocniczych, więc możesz ją serializować, cache’ować na dysku albo wysłać do workera.

Kompilacja z łańcucha

Gdy szablon nie pochodzi z systemu plików — z wiersza bazy danych, treści żądania, fikstury testowej — użyj compile() i nadaj mu nazwę na potrzeby komunikatów o błędach:

import { compile } from 'verso';

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

Przekazywanie danych

Pierwszy argument skompilowanego szablonu to obiekt danych. Właściwości są wyszukiwane z semantyką opcjonalnego łańcuchowania: brakująca wartość pośrednia daje pusty łańcuch, zamiast rzucać wyjątek.

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

Drugi argument zawiera opcje renderowania — wartości lokalne, które nie są częścią modelu danych, na przykład identyfikator żądania albo funkcję tłumaczącą:

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

W szablonie są dostępne jako {{@t('save')}} i {{@nonce}}. Przedrostek @ wyraźnie oddziela je od danych, co jest ważniejsze, niż się wydaje, gdy szablony rosną.

Strumieniowanie

Dla stron złożonych z kilku wolnych źródeł renderuj do strumienia zamiast do łańcucha. Verso wysyła każdy blok najwyższego poziomu, gdy tylko jest gotowy:

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

Bloki oznaczone {{#defer}} kończą się w dowolnej kolejności i są wstawiane na miejsce przez 400-bajtowy skrypt inline. Gdy JavaScript jest wyłączony, odroczone bloki pojawiają się na końcu dokumentu w kolejności źródłowej — w okrojonej formie, ale kompletnie.

Bundlery i kroki budowania

Prekompilacja szablonów trzyma parser z dala od produkcyjnej paczki. CLI zapisuje jeden moduł ES na szablon:

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

Oficjalne wtyczki istnieją dla Vite i esbuild, i obie mają około sześćdziesięciu linii — jeśli używasz czegoś innego, skopiowanie jednej z nich jest zwykle szybsze niż konfigurowanie ogólnego loadera.

Co dalej

Dokumentacja składni opisuje bloki, filtry i partiale. Dokumentacja API opisuje każdą eksportowaną funkcję i opcję. Jeśli wbudowujesz Verso w potok budowania, najkrótsza droga to dokumentacja CLI.