VoltroDocumentation

App templates

The scaffolding catalogue — every api / web / serverless template, what it demonstrates, and when to pick it.

Every template is a dogfooded, runnable reference. Scaffold one with voltro create-project --api <id> --web <id> (or voltro add-app <name> --template <id>), and run voltro list-templates for the live list.

Templates come in three kinds, matching the three things you deploy:

  • api — a long-running backend (app.config type: 'api').
  • web — a frontend (type: 'web'); gets a dev-server port.
  • serverless — a bundle of standalone *.serverless.ts functions shipped on their own with voltro serverless. No long-running server, no port — add it to a project with voltro add-app.

API backends (kind: api)

Template What you get
api-backend The minimal base: app.config + a *.entity.ts schema + one streaming query + one mutation. Tenant-aware out of the box. Start here.
api-backend-mail api-backend + @voltro/plugin-mail and a React-Email welcome template you preview/send from the dashboard.
api-backend-storage api-backend + @voltro/plugin-storage: public (CDN-direct) + private (policy + per-object grants) objects, with upload examples.
api-backend-mariadb MariaDB-backed: binlog CDC real-time, file storage, tenant-aware schema — the shape for K8s multi-replica apps.
api-durable The whole durable + reactive surface in one order-fulfillment domain: a workflow (step/sleep/awaitSignal), an event trigger, a cron schedule, a table subscriber, a materialized aggregate, and a startup hook.
api-ai A RAG support agent: a vectorEmbedding() docs table, a search tool, a real defineAgent/defineAgentExecutor model loop, and a generateObject action.
api-data-advanced The advanced schema DSL: *.entity.ts/*.relations.ts split + eager .with(), full-text search, dbEnum, array/generated/encrypted columns, and declarative query caching.
api-auth Real user auth — @voltro/plugin-auth turnkey: password sign-up/in/out over HttpOnly session cookies + a strategy resolving the session to a typed Subject. Zero-infra boot.
api-rest Public REST API — defineRestRoute (query/path/body, scope guards, Idempotency-Key) + @voltro/plugin-openapi (OpenAPI 3.1 spec + Swagger UI at /docs). Zero-infra boot.
api-saas The SaaS plugin bundle — billing entitlements + notifications + analytics + presence, wired turnkey; one projects.create exercises three together. Zero-infra boot.
api-observability Production-readiness — Prometheus /metrics + a custom counter, Sentry (inert without a DSN), tracing, and a @voltro/testing unit test (voltro test). Zero-infra boot.
api-webhooks First-class webhooks both ways — a signature-verified incoming *.webhook.tsx receiver + an outgoing defineOutgoingEvent emitted via a durable signed delivery workflow. Zero-infra boot.

Web frontends (kind: web)

Template Render mode What it demonstrates
frontend-blank — Empty React + layout shell + one page. The blank canvas.
frontend-app full · reactive The reactive end-to-end loop — a web frontend wired to an api (useSubscription + useMutation + auto-optimistic). The only fullstack template; pairs with api-backend.
frontend-landing static · interactive: 'none' Marketing page that ships zero JS on the wire.
frontend-static-blog static + islands SSG from a content source: dynamic [slug] routes pre-rendered via getStaticPaths, per-post meta from loader data, and ONE island (reading-progress bar) showing selective hydration.
frontend-spa spa A pure client-rendered tool — state lives in the browser (localStorage), so there's nothing to SSR. Shows where a single-page app is the right call.
frontend-ssr ssr + isr Server-rendered pages: a per-request SSR page (useServerRequest() for cookies/headers) + ISR pages (revalidate, staleWhileRevalidate, tenant-aware caching). Needs a runtime (voltro start), not a CDN. Self-contained; swap the loader for ctx.query to read from your api.
frontend-contact static + serverless Static page + a serverless email form (see combos below).
frontend-docs static (catch-all SSG) Docs site: docs/[...slug].tsx, per-section layout, URL-prefix i18n.
changelog static Release-notes site: MDX in content/releases/, rendered list + per-release pages, RSS feed.

Serverless functions (kind: serverless)

Template What you get
edge-functions A library of *.serverless.ts functions covering the range of what edge functions do — pure compute, request-header/geo, outbound HTTP (fire-and-forget + fetch-and-transform), Web Crypto HMAC verify, an LLM call, and status-controlled errors. Run with voltro serverless dev, ship to node / Cloudflare / Scaleway.

Static + serverless combos

The most common shape for a no-always-on-server product: a static page on a CDN + a serverless function for the one dynamic bit. Two templates show it:

  • frontend-contact — a static marketing page whose contact form (an island) POSTs to functions/sendMessage.serverless.ts, which sends mail via Resend. The page ships to a CDN; the function scales to zero. The function's local dev server sends CORS headers (same as the edge hosts), so the cross-origin form works out of the box.
  • edge-functions + any static web template — add the function library to a project that also has a frontend-static-blog or frontend-landing, and wire the page to whichever function it needs.
# Scaffold the combo:
voltro create-project acme --web frontend-contact --no-input
#   → apps/acme/contact/  (static page + functions/sendMessage.serverless.ts)

# Run both halves locally (two terminals):
pnpm --filter @acme/contact dev          # the static site
pnpm --filter @acme/contact fn:dev       # the serverless function on :8910

Picking a template

You want… Start with
A reactive backend (queries/mutations/workflows) api-backend (+ -mail / -storage for those features)
A marketing / brochure site frontend-landing
A blog or content site generated at build time frontend-static-blog
A heavily-interactive tool with no backend frontend-spa
Server-rendered pages (per-request SSR, or cached + revalidated ISR) frontend-ssr
A static site that needs ONE dynamic endpoint (email, webhook, …) frontend-contact
Docs frontend-docs
Standalone functions to deploy to the edge edge-functions

See also