@voltro/cli 0.1.0

package/templates/apps/frontend-landing/src/pages/index.test.tsx

@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+//
+// `/` — the bilingual landing template. A statically pre-rendered marketing
+// page with zero framework JS on the wire (`renderMode='static'`,
+// `interactive='none'`), localised per URL locale (Strategy B). Two things
+// worth testing:
+//   1. `meta({ locale })` is localized — it reads the REAL catalog via
+//      getCatalog, so we assert en vs de titles/descriptions directly (no mock).
+//   2. the rendered body shows localized copy. The page pulls strings from
+//      @voltro/i18n (<T>); we mock it to resolve against the real catalog for a
+//      controllable "current locale". The hero <h1> carries a `{{capProjectName}}`
+//      scaffold placeholder, so we assert the heading EXISTS, not its text.
+
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import en from '../locales/en'
+import de from '../locales/de'
+
+// Controllable "active locale" for the i18n mock.
+const catalogs: Record<string, Record<string, string>> = { en, de }
+let currentLocale = 'en'
+
+// Minimal ICU-ish interpolation: replace {key} with values[key]. Rich-text
+// tags (`<strong>`, `<code>`) are left inline as text — enough to assert the
+// page rendered the right (localized) copy; react-intl injects real elements.
+const fill = (msg: string, values?: Record<string, unknown>): string =>
+  values ? msg.replace(/\{(\w+)\}/g, (_, k: string) => String(values[k] ?? `{${k}}`)) : msg
+
+vi.mock('@voltro/i18n', () => ({
+  // The locale catalogs call these at module top-level; identity mirrors the
+  // real (compile-time-only) implementations so importing them doesn't throw.
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  T: ({ id, values }: { id: string; values?: Record<string, unknown> }) =>
+    fill(catalogs[currentLocale]?.[id] ?? id, values),
+}))
+
+const { default: Index, meta, renderMode, interactive } = await import('./index')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(node)
+  })
+}
+
+afterEach(() => {
+  currentLocale = 'en'
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('index — config + localized meta', () => {
+  test('is a static page with no interactive JS on the wire', () => {
+    expect(renderMode).toBe('static')
+    expect(interactive).toBe('none')
+  })
+
+  test('meta() returns the English catalog title/description for locale en', () => {
+    const m = meta({ locale: 'en' })
+    expect(m.title).toBe('Home')
+    expect(m.description).toContain('landing page')
+  })
+
+  test('meta() returns the German catalog title/description for locale de', () => {
+    const m = meta({ locale: 'de' })
+    expect(m.title).toBe('Start')
+    expect(m.description).toContain('Landingpage')
+  })
+
+  test('meta() falls back to the default (en) catalog for an unknown locale', () => {
+    expect(meta({ locale: 'zz' }).title).toBe('Home')
+  })
+})
+
+describe('index — localized render', () => {
+  test('renders a hero heading + the English Features section', () => {
+    currentLocale = 'en'
+    render(createElement(Index))
+    expect(container.querySelector('main h1')).toBeTruthy()
+    const featureSection = container.querySelector('#features')
+    expect(featureSection).toBeTruthy()
+    expect(featureSection!.querySelector('h2')!.textContent).toBe('Features')
+    const bullets = Array.from(container.querySelectorAll('#features li'))
+    expect(bullets).toHaveLength(3)
+    expect(container.textContent).toContain('Reactive subscriptions')
+    expect(container.querySelector('a[href="#features"]')).toBeTruthy()
+    expect(container.textContent).toContain('Ready to start?')
+  })
+
+  test('renders the German copy when the active locale is de', () => {
+    currentLocale = 'de'
+    render(createElement(Index))
+    expect(container.querySelector('#features h2')!.textContent).toBe('Funktionen')
+    expect(container.textContent).toContain('Reaktive Subscriptions')
+    expect(container.textContent).toContain('Bereit loszulegen?')
+  })
+})

package/templates/apps/frontend-landing/src/pages/index.tsx

@@ -0,0 +1,75 @@
+// Landing page for the {{projectName}} project. Pre-rendered at build time
+// by `voltro build` (renderMode='static'), then served straight from the
+// file system by `voltro start`. `interactive='none'` strips ALL framework
+// JS from the wire — each locale is plain, pre-rendered HTML + CSS.
+//
+// Bilingual (Strategy B): mounted at `/` (default locale) and mirrored at
+// `/de` by src/pages/[locale]/index.tsx. `meta` is a FUNCTION of `{ locale }`
+// so each variant's <title> / <description> is localised in the emitted HTML.
+
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T } from '@voltro/i18n'
+import { getCatalog } from '../lib/locale'
+
+// Pre-render at build time. Removes the runtime dependency entirely
+// for plain-content pages — no rpc client, no react hydration. If you
+// later add a sign-up form or anything interactive, switch to
+// `interactive: 'islands'` and mark the form component as an island.
+export const renderMode = 'static' as const
+export const interactive = 'none' as const
+
+export const meta = ({ locale }: { locale: string }): PageMeta => {
+  const c = getCatalog(locale)
+  return {
+    title: c['meta.home.title'],
+    description: c['meta.home.description'],
+  }
+}
+
+// Rich-text tag handlers — each `<tag>` used inside a message needs a
+// matching value function so react-intl injects the real element.
+const strong = (chunks: ReactNode): ReactNode => <strong>{chunks}</strong>
+const code = (chunks: ReactNode): ReactNode => <code>{chunks}</code>
+
+export default function Index(): ReactNode {
+  return (
+    <main>
+      <section>
+        <h1>{{capProjectName}}</h1>
+        <p>
+          <T id="hero.tagline" />
+        </p>
+        <a href="#features">
+          <T id="hero.cta" />
+        </a>
+      </section>
+
+      <section id="features">
+        <h2>
+          <T id="features.heading" />
+        </h2>
+        <ul>
+          <li>
+            <T id="features.reactive" values={{ strong }} />
+          </li>
+          <li>
+            <T id="features.tenant" values={{ strong }} />
+          </li>
+          <li>
+            <T id="features.conventions" values={{ strong, code }} />
+          </li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>
+          <T id="cta.heading" />
+        </h2>
+        <p>
+          <T id="cta.body" values={{ code }} />
+        </p>
+      </section>
+    </main>
+  )
+}

package/templates/apps/frontend-landing/src/pages/layout.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+//
+// Root layout — renders the top nav whose Home link + language switcher are
+// locale-prefixed off the CURRENT url (useUrlLocale → useLocation). We mock
+// useLocation (@voltro/web) to drive the active locale, and mock @voltro/i18n so
+// <I18nProvider> is a pass-through and <T> resolves against the real catalogs.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import en from '../locales/en'
+import de from '../locales/de'
+
+const location = vi.fn<() => string>()
+vi.mock('@voltro/web', () => ({ useLocation: () => location() }))
+
+const catalogs: Record<string, Record<string, string>> = { en, de }
+const localeFor = (path: string): string => (/^\/de(?:\/|$)/.test(path) ? 'de' : 'en')
+
+vi.mock('@voltro/i18n', () => ({
+  // The locale catalogs call these at module top-level; identity mirrors the
+  // real (compile-time-only) implementations so importing them doesn't throw.
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  I18nProvider: ({ children }: { children?: ReactNode }) => children,
+  // The nav uses <T> for link labels; resolve against the catalog of the
+  // locale implied by the current path (matches what useUrlLocale computes).
+  T: ({ id }: { id: string }) => catalogs[localeFor(location())]?.[id] ?? id,
+}))
+
+const { default: Layout } = await import('./layout')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(node)
+  })
+}
+
+const hrefs = (): Array<string | null> =>
+  Array.from(container.querySelectorAll('a')).map((a) => a.getAttribute('href'))
+
+beforeEach(() => location.mockReset())
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('landing layout — English (bare path)', () => {
+  test('renders a bare Home link, an English nav label and the DE switcher target', () => {
+    location.mockReturnValue('/')
+    render(createElement(Layout, { children: createElement('p', null, 'page') }))
+    const h = hrefs()
+    expect(h).toContain('/')
+    // the language switcher keeps you on the same bare page, re-prefixed per locale
+    expect(h).toContain('/de')
+    expect(container.textContent).toContain('Home')
+    expect(container.textContent).toContain('page')
+  })
+})
+
+describe('landing layout — German (/de prefix)', () => {
+  test('prefixes the home link with /de and renders German labels', () => {
+    location.mockReturnValue('/de')
+    render(createElement(Layout, { children: null }))
+    const h = hrefs()
+    expect(h).toContain('/de')
+    // switching back to en strips the prefix
+    expect(h).toContain('/')
+    expect(container.textContent).toContain('Start')
+  })
+})

package/templates/apps/frontend-landing/src/pages/layout.tsx

@@ -0,0 +1,66 @@
+// Root layout. Strategy B (URL-prefix i18n): an INNER <I18nProvider> reads
+// the locale FROM THE URL, so the pre-render pipeline resolves the right
+// catalog per locale-prefixed path (and client-side nav swaps it without a
+// full reload). The language switcher is plain <a> links — no JS needed, so
+// this stays compatible with the pages' `interactive: 'none'`.
+//
+// `<html>`/`<head>`/`<body>` are owned by the framework shell — don't render
+// them here. Page <title> + meta come from each page's `meta` export.
+
+import type { ReactNode } from 'react'
+import { I18nProvider, T } from '@voltro/i18n'
+import { useLocation } from '@voltro/web'
+import {
+  CATALOGS,
+  DEFAULT_LOCALE,
+  SUPPORTED_LOCALES,
+  stripLocalePrefix,
+  useUrlLocale,
+  withLocalePrefix,
+} from '../lib/locale'
+import '../globals.css'
+
+function TopNav(): ReactNode {
+  const locale = useUrlLocale()
+  // The path WITHOUT its locale prefix — so the language switch keeps you
+  // on the same page (e.g. /de → /, then re-prefix per locale).
+  const barePath = stripLocalePrefix(useLocation())
+
+  // Plain <a> (not <Link>): these hrefs are COMPUTED per locale, and
+  // <Link to> wants a statically-known `VoltroUrl` literal. Each language
+  // is its own crawlable URL, reached by a full navigation.
+  return (
+    <nav className="topnav">
+      <a href={withLocalePrefix('/', locale)}>
+        <T id="nav.home" />
+      </a>
+      <span className="spacer" />
+      <span className="lang">
+        <span className="label">
+          <T id="nav.language" />:
+        </span>
+        {SUPPORTED_LOCALES.map((code) => (
+          <a
+            key={code}
+            href={withLocalePrefix(barePath, code)}
+            aria-current={code === locale ? 'true' : undefined}
+          >
+            {code.toUpperCase()}
+          </a>
+        ))}
+      </span>
+    </nav>
+  )
+}
+
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  const locale = useUrlLocale()
+  return (
+    <I18nProvider locale={locale} messages={CATALOGS[locale]} defaultLocale={DEFAULT_LOCALE}>
+      <div className="shell">
+        <TopNav />
+        {children}
+      </div>
+    </I18nProvider>
+  )
+}

package/templates/apps/frontend-landing/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-landing",
+  "kind": "web",
+  "summary": "Bilingual (en/de) marketing landing page: hero, features grid, CTA. Static-render mode with zero JS on the wire; URL-prefix i18n (`/` + `/de`) pre-renders one HTML file per locale. Flip interactive: 'islands' for interactive pieces.",
+  "tags": ["web", "frontend", "landing", "marketing", "static", "i18n", "intl", "localization"]
+}

package/templates/apps/frontend-landing/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", ".framework"]
+}

package/templates/apps/frontend-spa/README.md

@@ -0,0 +1,45 @@
+# {{projectName}} / {{appName}}
+
+Pure SPA (template: **frontend-spa**) — a fully client-rendered tool
+with no backend and no SSR.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+```
+
+## When to reach for `renderMode: 'spa'`
+
+Use it when the page is heavily interactive AND its state lives in the
+browser, so a server-rendered first paint would just be discarded on
+hydration. This template's bill splitter is the canonical case: every
+input is interactive and the last tip % is remembered in `localStorage`
+— there is nothing meaningful for the server to render.
+
+For content pages (marketing, blog, docs) prefer `renderMode: 'static'`
+and reach for `island()` when only a few widgets are interactive — see
+the **frontend-static-blog** template. Use `spa` only when the JS *is*
+the page.
+
+## What this template demonstrates
+
+| Concept | Where |
+|---|---|
+| `renderMode = 'spa'` (client-render, no pre-render) | `src/pages/index.tsx` |
+| Default `interactive: 'full'` (whole tree hydrates) | `src/pages/index.tsx` |
+| Browser-only state via `localStorage` (read in an effect) | `src/pages/index.tsx` |
+| Zero backend — no rpc client, no loader | the whole app |
+
+## Build + serve
+
+```bash
+pnpm --filter @{{projectName}}/{{appName}} build
+pnpm --filter @{{projectName}}/{{appName}} start
+# or push the static dist/ to a CDN:
+voltro static deploy --host cloudflare-pages --project-name {{appName}} --spa
+```
+
+The `--spa` flag serves `index.html` for unknown routes — the correct
+fallback for a single-page app on a CDN.

package/templates/apps/frontend-spa/app.config.ts

@@ -0,0 +1,27 @@
+// Web app for the {{projectName}} project — a pure SPA (single-page app).
+//
+// Pages here set `renderMode = 'spa'`: the framework skips pre-rendering
+// and the client renders on load. That is the right call when the page's
+// state lives entirely in the browser (here: localStorage), so an SSR'd
+// first paint would just be thrown away on hydration.
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  theme: 'system' as const,
+  env,
+  // Bilingual by default. The framework auto-wires a cookie-driven
+  // <I18nProvider> from these codes and loads the matching
+  // `src/locales/<code>.ts` catalog — so `<T id="…" />` / `useT()` /
+  // `useLocale()` work app-wide with no manual setup. The <LocaleSwitcher>
+  // in the layout writes the `voltro:lang` cookie + reloads. Grow the app to
+  // more languages by adding a code here + a `src/locales/<code>.ts`.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+}

package/templates/apps/frontend-spa/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@voltro/cli": "0.1.0",
+    "@voltro/client": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/i18n": "0.1.0",
+    "@voltro/ui-shadcn": "0.1.0",
+    "@voltro/web": "0.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/frontend-spa/src/globals.css

@@ -0,0 +1,84 @@
+/* Self-contained styles — plain CSS, no Tailwind / kit dependency. */
+
+:root {
+  --bg: #f4f4f5;
+  --card: #ffffff;
+  --fg: #18181b;
+  --muted: #71717a;
+  --accent: #0d9488;
+  --border: #e4e4e7;
+}
+
+:root.dark {
+  --bg: #09090b;
+  --card: #18181b;
+  --fg: #fafafa;
+  --muted: #a1a1aa;
+  --accent: #2dd4bf;
+  --border: #27272a;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; min-height: 100vh; }
+
+body {
+  background: var(--bg);
+  color: var(--fg);
+  font: 16px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  display: flex;
+  justify-content: center;
+  padding: 3rem 1rem;
+}
+
+.card {
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  padding: 1.75rem;
+  width: 100%;
+  max-width: 26rem;
+  box-shadow: 0 1px 3px rgb(0 0 0 / 0.06);
+}
+
+h1 { font-size: 1.4rem; margin: 0 0 0.25rem; }
+.muted { color: var(--muted); font-size: 0.9rem; margin: 0 0 1.5rem; }
+
+label { display: block; font-size: 0.85rem; color: var(--muted); margin: 1rem 0 0.35rem; }
+
+input[type="number"], input[type="text"] {
+  width: 100%;
+  padding: 0.6rem 0.75rem;
+  font-size: 1rem;
+  color: var(--fg);
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+
+.row { display: flex; gap: 0.75rem; }
+.row > div { flex: 1; }
+
+.presets { display: flex; gap: 0.5rem; margin-top: 0.5rem; flex-wrap: wrap; }
+.presets button {
+  flex: 1;
+  padding: 0.5rem;
+  font-size: 0.9rem;
+  border: 1px solid var(--border);
+  background: var(--bg);
+  color: var(--fg);
+  border-radius: 8px;
+  cursor: pointer;
+}
+.presets button.active { border-color: var(--accent); color: var(--accent); font-weight: 600; }
+
+.result {
+  margin-top: 1.75rem;
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--border);
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+}
+.result .big { font-size: 2rem; font-weight: 700; color: var(--accent); }
+.result .line { display: flex; justify-content: space-between; font-size: 0.95rem; }
+.result .col { display: flex; flex-direction: column; gap: 0.4rem; flex: 1; }

package/templates/apps/frontend-spa/src/locales/de.ts

@@ -0,0 +1,22 @@
+// German catalog. Mirrors every key in `en.ts` — `defineLocale<typeof en>()`
+// fails the build if a key is missing or misspelled. Translate the prose only;
+// keep ICU placeholders and rich tags identical to `en.ts`.
+
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.home.title': 'Rechnungsteiler',
+
+  'lang.label': 'Sprache',
+
+  'home.heading':      'Rechnungsteiler',
+  'home.subtitle':     '100 % im Browser · dein letztes Trinkgeld wird lokal gemerkt',
+  'field.bill':        'Rechnungsbetrag',
+  'field.tip':         'Trinkgeld',
+  'field.custom':      'Eigener %',
+  'field.people':      'Personen',
+  'result.tip':        'Trinkgeld',
+  'result.total':      'Gesamt',
+  'result.perPerson':  'pro Person',
+})

package/templates/apps/frontend-spa/src/locales/en.ts

@@ -0,0 +1,29 @@
+// Base catalog — the source of truth for this app's UI strings. Every key here
+// MUST be mirrored in `de.ts` (and any other locale); `defineLocale<typeof en>()`
+// enforces that parity at build time, so a missing translation fails typecheck
+// rather than silently falling back.
+//
+// Messages use ICU syntax: `{name}` placeholders, `{n, plural, …}`, and rich
+// tags like `<code>…</code>` (rendered by passing a matching function to
+// `<T values={{ code: (c) => <code>{c}</code> }} />`).
+
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  // Browser tab title — locale-aware via the page's `meta({ locale })`.
+  'meta.home.title': 'Bill splitter',
+
+  // ---- Layout shell (pages/layout.tsx) ----
+  'lang.label': 'Language',
+
+  // ---- Bill-splitter page (pages/index.tsx) ----
+  'home.heading':      'Bill splitter',
+  'home.subtitle':     '100% client-side · your last tip % is remembered locally',
+  'field.bill':        'Bill amount',
+  'field.tip':         'Tip',
+  'field.custom':      'Custom %',
+  'field.people':      'People',
+  'result.tip':        'Tip',
+  'result.total':      'Total',
+  'result.perPerson':  'per person',
+} as const)

package/templates/apps/frontend-spa/src/locales/index.ts

@@ -0,0 +1,15 @@
+// Catalog lookup OUTSIDE React — for a page's `meta({ locale })` locale-aware
+// <title>. This app is cookie-i18n (no `/<locale>` URL prefix), so @voltro/web
+// hands `meta` the active locale from the `voltro:lang` cookie. Inside React,
+// use `<T>` / `useT()` via the framework's auto-wired <I18nProvider> instead.
+
+import en from './en'
+import de from './de'
+
+// Both catalogs share `en`'s keys (defineLocale enforces the mirror), so a
+// known-key lookup returns `string` — not `string | undefined` — which is what
+// `PageMeta.title` requires under exactOptionalPropertyTypes.
+export type Messages = Record<keyof typeof en, string>
+
+export const getCatalog = (locale?: string): Messages =>
+  (locale === 'de' ? de : en) as Messages