@voltro/cli 0.28.0 → 0.29.0

package/templates/apps/frontend-cms/src/pages/(app)/page.tsx

@@ -0,0 +1,159 @@
+// The editor — URL `/`. Introspects the api's registered content types
+// (`content.types`) and generates a form per type with @voltro/cms's
+// `<ContentForm>`; lists a type's drafts live (`content.list`), saves them
+// (`content.saveDraft`, with per-field validation surfaced inline), and
+// publishes / unpublishes them. One page, no dynamic routes — the selected type
+// and the row being edited are component state.
+import type { ReactNode } from 'react'
+import { useEffect, useMemo, useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { useAction, useMutation, useSubscription } from '@voltro/client'
+import { ContentForm } from '@voltro/cms/web'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+import {
+  toContentFormType,
+  type ContentRow,
+  type ContentTypeDescriptor,
+  type SaveResult,
+} from '../../lib/api'
+
+export const renderMode = 'ssr' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.editor.title'],
+})
+
+interface Violation { readonly field: string; readonly rule: string; readonly message: string }
+
+export default function Editor(): ReactNode {
+  const types = useAction<Record<string, never>, { types: ReadonlyArray<ContentTypeDescriptor> }>(
+    'cms', 'content.types',
+  )
+  const getOne = useAction<{ type: string; id: string; status: string }, { row: Record<string, unknown> | null }>(
+    'cms', 'content.get',
+  )
+  const save = useMutation<{ type: string; values: Record<string, unknown> }, SaveResult>('cms', 'content.saveDraft')
+  const publish = useMutation<{ type: string; id: string }, { ok: boolean }>('cms', 'content.publish')
+  const unpublish = useMutation<{ type: string; id: string }, { ok: boolean }>('cms', 'content.unpublish')
+
+  const [typeList, setTypeList] = useState<ReadonlyArray<ContentTypeDescriptor>>([])
+  const [active, setActive] = useState<string | null>(null)
+  const [values, setValues] = useState<Record<string, unknown>>({})
+  const [editingId, setEditingId] = useState<string | null>(null)
+  const [violations, setViolations] = useState<ReadonlyArray<Violation>>([])
+  const [saved, setSaved] = useState(false)
+
+  // Load the content types once; select the first.
+  useEffect(() => {
+    void types.run({}).then((r) => {
+      setTypeList(r.types)
+      setActive((cur) => cur ?? r.types[0]?.name ?? null)
+    })
+  }, []) // mount-only fetch of the content-type descriptors
+
+  const activeType = typeList.find((t) => t.name === active) ?? null
+
+  // Live drafts of the active type. Memoised input so a stable object identity
+  // avoids resubscribing every render; an unset/unknown type yields an empty list.
+  const listInput = useMemo(() => ({ type: active ?? '—', status: 'draft' as const }), [active])
+  const { data: rows } = useSubscription<ReadonlyArray<ContentRow>>('cms', 'content.list', listInput)
+  const drafts = rows ?? []
+
+  const resetForm = (): void => { setValues({}); setEditingId(null); setViolations([]) }
+
+  const onSelectType = (name: string): void => { setActive(name); resetForm(); setSaved(false) }
+
+  const onEdit = (id: string): void => {
+    if (active === null) return
+    void getOne.run({ type: active, id, status: 'draft' }).then((r) => {
+      if (r.row) { setValues(r.row); setEditingId(id); setViolations([]); setSaved(false) }
+    })
+  }
+
+  const onSubmit = (e: FormEvent): void => {
+    e.preventDefault()
+    if (active === null) return
+    const payload = editingId ? { ...values, id: editingId } : values
+    void save.mutate({ type: active, values: payload }).then((res) => {
+      if (res.ok) { resetForm(); setSaved(true) } else { setViolations(res.violations); setSaved(false) }
+    })
+  }
+
+  const onPublish = (id: string): void => { if (active) void publish.mutate({ type: active, id }) }
+  const onUnpublish = (id: string): void => { if (active) void unpublish.mutate({ type: active, id }) }
+
+  const statusKey = (s: string): 'editor.status.draft' | 'editor.status.published' | 'editor.status.archived' =>
+    s === 'published' ? 'editor.status.published' : s === 'archived' ? 'editor.status.archived' : 'editor.status.draft'
+
+  if (typeList.length === 0) {
+    return <section className="cms-main"><p className="empty"><T id="editor.form.loading" /></p></section>
+  }
+
+  return (
+    <div className="cms-grid">
+      {/* Left: type chooser + live draft list */}
+      <section className="cms-list">
+        <h2 className="label"><T id="editor.types.heading" /></h2>
+        <nav className="cms-types">
+          {typeList.map((t) => (
+            <button
+              key={t.name} type="button"
+              className={t.name === active ? 'chip active' : 'chip'}
+              onClick={() => onSelectType(t.name)}
+            >
+              {t.displayName}
+            </button>
+          ))}
+        </nav>
+
+        <h3 className="label" style={{ marginTop: '1rem' }}>
+          <T id="editor.list.heading" values={{ type: activeType?.pluralName ?? '' }} />
+        </h3>
+        {drafts.length === 0 ? (
+          <p className="empty"><T id="editor.list.empty" /></p>
+        ) : (
+          <ul className="rows">
+            {drafts.map((row) => (
+              <li key={row.id}>
+                <span className="grow">{row.title ?? row.slug ?? row.id}</span>
+                <span className="tag"><T id={statusKey(row.status)} /></span>
+                <button type="button" className="link" onClick={() => onEdit(row.id)}><T id="editor.row.edit" /></button>
+                <button type="button" className="link" onClick={() => onPublish(row.id)}><T id="editor.row.publish" /></button>
+                <button type="button" className="link" onClick={() => onUnpublish(row.id)}><T id="editor.row.unpublish" /></button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+
+      {/* Right: the auto-generated form */}
+      <section className="cms-editor">
+        <h2>
+          {editingId
+            ? <T id="editor.form.editing" />
+            : <T id="editor.form.new" values={{ type: activeType?.displayName ?? '' }} />}
+        </h2>
+        {activeType ? (
+          <form onSubmit={onSubmit}>
+            <ContentForm contentType={toContentFormType(activeType)} value={values} onChange={setValues} />
+            {violations.length > 0 ? (
+              <ul className="violations" role="alert">
+                {violations.map((v) => <li key={v.field + v.rule}>{v.field}: {v.message}</li>)}
+              </ul>
+            ) : null}
+            {saved ? <p className="ok"><T id="editor.form.saved" /></p> : null}
+            <div className="row" style={{ marginTop: '0.75rem' }}>
+              <button type="submit" className="btn" disabled={save.pending}>
+                <T id={save.pending ? 'editor.form.saving' : 'editor.form.save'} />
+              </button>
+              {editingId ? (
+                <button type="button" className="btn ghost" onClick={resetForm}><T id="editor.form.cancel" /></button>
+              ) : null}
+            </div>
+          </form>
+        ) : null}
+      </section>
+    </div>
+  )
+}

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

@@ -0,0 +1,12 @@
+// Root layout — wraps EVERY page (marketing + dashboard). Thin: it loads the
+// stylesheet and lets each AREA layout ((marketing)/layout.tsx,
+// dashboard/layout.tsx) supply its own chrome. Layouts nest, so a dashboard
+// page is wrapped root → dashboard.
+//
+// Don't render <html>/<head>/<body> here — the framework shell owns them.
+import type { ReactNode } from 'react'
+import '../globals.css'
+
+export default function RootLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  return <>{children}</>
+}

package/templates/apps/frontend-cms/src/pages/login/page.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+//
+// The auth form. We assert config + that it renders email/password fields and
+// toggles between sign-in and sign-up. The network submit (CSRF + POST /auth/*)
+// is exercised against a running api by `voltro dev`, not unit-mocked here.
+
+import { afterEach, describe, expect, test } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../../locales/en'
+
+const { default: Login, meta, renderMode } = await import('./page')
+
+;(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(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('login — config', () => {
+  test('is a static page titled Sign in', () => {
+    expect(renderMode).toBe('static')
+    expect(meta({ locale: 'en' }).title).toBe('Sign in')
+  })
+})
+
+describe('login — form', () => {
+  test('renders email + password inputs and defaults to sign-in', () => {
+    render(createElement(Login))
+    expect(container.querySelector('input[type="email"]')).not.toBeNull()
+    expect(container.querySelector('input[type="password"]')).not.toBeNull()
+    expect(container.querySelector('h1')?.textContent).toBe('Sign in to the CMS')
+  })
+
+  test('toggling switches to the create-account heading', () => {
+    render(createElement(Login))
+    const toggle = container.querySelector('.link')!
+    act(() => { toggle.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+    expect(container.querySelector('h1')?.textContent).toBe('Create an editor account')
+  })
+})

package/templates/apps/frontend-cms/src/pages/login/page.tsx

@@ -0,0 +1,93 @@
+// Sign in / sign up — URL `/login`. A REAL auth form: it POSTs to the api's
+// `/auth/*` routes (contributed by @voltro/plugin-auth on api-cms), which set
+// the HttpOnly session cookie. State-changing auth routes are CSRF-protected, so
+// we fetch a token first. On success we do a FULL navigation so the editor's SSR
+// gate re-runs with the freshly-set cookie.
+import type { ReactNode } from 'react'
+import { useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useT } from '@voltro/i18n'
+import { getCatalog } from '../../locales'
+
+export const renderMode = 'static' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.login.title'],
+})
+
+type Mode = 'signIn' | 'signUp'
+
+async function submitAuth(mode: Mode, email: string, password: string): Promise<boolean> {
+  const csrf = (await fetch('/auth/csrf').then((r) => r.json())) as { csrfToken: string }
+  const path = mode === 'signUp' ? '/auth/sign-up' : '/auth/sign-in'
+  const res = await fetch(path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-csrf-token': csrf.csrfToken },
+    body: JSON.stringify({ email, password }),
+  })
+  return res.ok
+}
+
+export default function Login(): ReactNode {
+  const [mode, setMode] = useState<Mode>('signIn')
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [pending, setPending] = useState(false)
+  const [failed, setFailed] = useState(false)
+  const emailLabel = useT('auth.email')
+  const passwordLabel = useT('auth.password')
+
+  const onSubmit = (e: FormEvent): void => {
+    e.preventDefault()
+    setPending(true)
+    setFailed(false)
+    void submitAuth(mode, email, password)
+      .then((ok) => {
+        if (ok) {
+          const from = new URLSearchParams(window.location.search).get('from') ?? '/'
+          window.location.assign(from)
+        } else {
+          setFailed(true)
+          setPending(false)
+        }
+      })
+      .catch(() => {
+        setFailed(true)
+        setPending(false)
+      })
+  }
+
+  return (
+    <section className="hero">
+      <h1><T id={mode === 'signUp' ? 'auth.signUp.heading' : 'auth.signIn.heading'} /></h1>
+      <form className="auth-form" onSubmit={onSubmit}>
+        <label>
+          <span><T id="auth.email" /></span>
+          <input
+            type="email" required aria-label={emailLabel} value={email}
+            onChange={(e) => setEmail(e.target.value)}
+          />
+        </label>
+        <label>
+          <span><T id="auth.password" /></span>
+          <input
+            type="password" required aria-label={passwordLabel} value={password}
+            onChange={(e) => setPassword(e.target.value)}
+          />
+        </label>
+        {failed ? <p className="error-text"><T id="auth.error" /></p> : null}
+        <button type="submit" className="btn" disabled={pending}>
+          <T id={pending ? 'auth.pending' : mode === 'signUp' ? 'auth.signUp.submit' : 'auth.signIn.submit'} />
+        </button>
+      </form>
+      <p style={{ marginTop: '1rem' }}>
+        <button
+          type="button" className="link"
+          onClick={() => { setMode((m) => (m === 'signIn' ? 'signUp' : 'signIn')); setFailed(false) }}
+        >
+          <T id={mode === 'signIn' ? 'auth.toggle.toSignUp' : 'auth.toggle.toSignIn'} />
+        </button>
+      </p>
+    </section>
+  )
+}

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

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-cms",
+  "kind": "web",
+  "summary": "The CMS editor UI for the api-cms backend: a sign-in page (POST /auth/*), an SSR auth gate (session.me → redirect anonymous editors to /login), and a content editor that fetches the registered content types (content.types) and auto-generates a form per type with @voltro/cms's <ContentForm> — create/edit drafts (content.saveDraft, validation surfaced inline), live-list them (content.list), and publish/unpublish. Bilingual (en/de).",
+  "tags": ["web", "frontend", "cms", "editor", "content", "auth", "ssr", "ContentForm"]
+}

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

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -15,18 +15,18 @@
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/client": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/i18n": "0.28.0",
-    "@voltro/serverless": "0.28.0",
-    "@voltro/web": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/serverless": "0.29.0",
+    "@voltro/web": "0.29.0",
     "effect": "^3.22.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.28.0",
+    "@voltro/devtools": "0.29.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3",

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

@@ -12,17 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.28.0",
-    "@voltro/client": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/i18n": "0.28.0",
-    "@voltro/ui-shadcn": "0.28.0",
-    "@voltro/web": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/ui-shadcn": "0.29.0",
+    "@voltro/web": "0.29.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.28.0",
+    "@voltro/devtools": "0.29.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3",

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

@@ -12,17 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.28.0",
-    "@voltro/client": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/i18n": "0.28.0",
-    "@voltro/ui-shadcn": "0.28.0",
-    "@voltro/web": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/ui-shadcn": "0.29.0",
+    "@voltro/web": "0.29.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.28.0",
+    "@voltro/devtools": "0.29.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3",

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

@@ -12,16 +12,16 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.28.0",
-    "@voltro/client": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/i18n": "0.28.0",
-    "@voltro/web": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/web": "0.29.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.28.0",
+    "@voltro/devtools": "0.29.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3",

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

@@ -12,17 +12,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/cli": "0.28.0",
-    "@voltro/client": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/i18n": "0.28.0",
-    "@voltro/ui-shadcn": "0.28.0",
-    "@voltro/web": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/ui-shadcn": "0.29.0",
+    "@voltro/web": "0.29.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.28.0",
+    "@voltro/devtools": "0.29.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3",

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

@@ -0,0 +1,71 @@
+# {{capProjectName}} {{capAppName}} — billing & account portal
+
+The lean "manage your account" surface customers visit outside the product:
+plan, payment method, invoices, API keys, profile. Consumes the
+**api-saas-starter** backend; billing is plugin-orchestrated, so the template
+never renders an invoice or holds a card. Bilingual (en/de).
+
+```bash
+voltro init my-saas --api=api-saas-starter --web=frontend-portal
+```
+
+## Pages
+
+| URL | Reads / drives | Notes |
+|---|---|---|
+| `/` | `billing.subscription` | overview: plan, status, renewal + quick links |
+| `/billing` | `billing.subscription`, `billing.portalUrl`, `billing.previewChange`, `billing.changePlan` | plan card; card management redirects to the provider portal; a plan change QUOTES the provider's proration before applying |
+| `/invoices` | `billing.invoices` | list; "View" / "PDF" link out to the provider's hosted pages |
+| `/api-keys` | `GET/POST /v1/api-keys*` | the framework's built-in key management (see below) |
+| `/profile` | `session.me`, `/auth/password-reset`, `/auth/sign-out` | identity, self-serve password reset, sign out |
+| `/login` | `POST /auth/*` | sign-in / sign-up |
+
+`(portal)/layout.tsx` is the SSR auth gate — it asks `session.me` server-side and
+RedirectErrors an anonymous visitor to `/login`.
+
+## API keys — one config step on the API
+
+The API-keys page drives the framework's **built-in** management surface
+(`/v1/api-keys`), which the API exposes only when it sets `apiKeys: true` in its
+`app.config.ts`. **api-saas-starter does not enable it by default**, so out of the
+box this page shows a clear "enable it" notice rather than a broken table. To make
+it live:
+
+1. On the API: `export default { …, apiKeys: true }`.
+2. Grant the signed-in user an issuing scope (`apikey:issue:self`) or `admin` —
+   the management routes are admin-scoped by design (keys are org credentials).
+
+The raw key is shown exactly **once** at mint time (hash-stored, unrecoverable).
+The page degrades on `404` (not enabled), `401/403` (no scope), and errors.
+
+## What's intentionally NOT here
+
+Per the lean brief: **no** support-ticket system and **no** team/member
+management — those belong in the product's own dashboard or a dedicated tool.
+Seat changes stay with the dashboard (`billing.changeSeats`); this portal is plan,
+payment, invoices, keys, profile.
+
+## Files
+
+```
+app.config.ts                       web app; apis.app → @{{projectName}}/api (api-saas-starter)
+src/lib/api.ts                      wire shapes (subscription/invoice/apiKey) + formatMoney
+src/pages/
+  login/page.tsx(.test)             sign-in / sign-up (POST /auth/*)
+  (portal)/layout.tsx(.test)        shell + SSR auth gate (session.me)
+  (portal)/page.tsx                 overview
+  (portal)/billing/page.tsx(.test)  plan + payment method + quoted plan change
+  (portal)/invoices/page.tsx        invoice history (links out)
+  (portal)/api-keys/page.tsx(.test) framework key management (graceful)
+  (portal)/profile/page.tsx         identity + password reset + sign out
+  (portal)/error.tsx · not-found.tsx
+src/locales/{en,de}.ts              bilingual catalogs (parity-enforced)
+```
+
+## Going to production
+
+- **Real Stripe** — configure `billingPlugin({ provider: 'stripe', … })` on the
+  API; `billing.portalUrl` then opens Stripe's real hosted portal and
+  `billing.invoices` returns real `hostedUrl`/`pdfUrl` links.
+- **Email** — wire `sendEmail` on the API so the profile password-reset actually
+  delivers.

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

@@ -0,0 +1,37 @@
+// Web app for the {{projectName}} project — the customer BILLING + ACCOUNT
+// portal over the sibling `api-saas-starter` api. Slim by design: the screens a
+// customer visits to manage their account OUTSIDE the product — plan, payment
+// method, invoices, API keys, profile.
+//
+//   - `/login` — static sign-in that POSTs to the api's `/auth/*`.
+//   - The authed portal in the SILENT route group `src/pages/(portal)/`. Its
+//     `layout.tsx` loader is the auth gate (asks the api's `session.me`,
+//     RedirectErrors an anonymous visitor to /login). Its pages are
+//     `renderMode: 'ssr'` so the gate runs per request.
+//
+// Billing is plugin-orchestrated: `billing.subscription` / `billing.invoices`
+// are live reads, and card management / plan changes go through the provider via
+// `billing.portalUrl` / `billing.changePlan` — the template never renders an
+// invoice or holds a card itself.
+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,
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  // The api this portal consumes. Pair with api-saas-starter:
+  // `voltro init my-saas --api=api-saas-starter --web=frontend-portal`.
+  // The hooks pass 'app' as the lookup key; codegen pulls its typed rpc surface
+  // (session.me + the billing plugin's `billing.*`).
+  apis: {
+    app: { package: '@{{projectName}}/api' },
+  },
+}

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

@@ -0,0 +1,32 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@{{projectName}}/api": "0.29.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/ui-shadcn": "0.29.0",
+    "@voltro/web": "0.29.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@voltro/devtools": "0.29.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/frontend-portal/src/config.ts

@@ -0,0 +1,8 @@
+// The brand name shown in the marketing header + dashboard sidebar.
+//
+// A plain constant — not `publicEnv` — so the template typechecks BEFORE
+// `voltro dev` generates the env types. `VOLTRO_PUBLIC_APP_NAME` is still
+// declared in app.config.ts (validated + in the env manifest); to read it typed
+// instead, after one `voltro dev` swap this for
+// `publicEnv.VOLTRO_PUBLIC_APP_NAME` from '@voltro/env/public'.
+export const APP_NAME = '{{capProjectName}}'