@voltro/cli 0.53.0 → 0.54.0

package/templates/apps/frontend-landing/src/fonts/LICENSE-Geist.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2023 Vercel, in collaboration with basement.studio
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

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

@@ -11,8 +11,23 @@
  * vite-plugin auto-detect stops firing. */
 @source "./**/*.{tsx,ts,jsx,js}";
 
+/* Point the kit's `--font-sans` at the family the framework's font pipeline
+ * self-hosts. `--font-geist` is defined by the generated shell (the
+ * `<style data-voltro-fonts>` block) from the `fonts:` declaration in
+ * app.config.ts, and expands to `'Geist', 'Geist Fallback', Arial,
+ * sans-serif` — the second entry being the size-adjusted metric fallback the
+ * pipeline computes, which is what keeps the swap from moving any text.
+ *
+ * Without this line the declaration would still self-host the file, but no
+ * rule would reference the family: the page would ship a font it never uses. */
+:root {
+  --font-sans: var(--font-geist);
+}
+
 html, body { min-height: 100vh; }
 
+body { font-family: var(--font-sans); }
+
 /* Gradient title — use on hero <h1> via `className="gradient-title"`. */
 .gradient-title {
   background: linear-gradient(180deg, var(--foreground) 0%, oklch(0.7 0.18 290) 100%);

package/templates/apps/frontend-landing/src/globals.d.ts

@@ -4,3 +4,20 @@
 // rejects a bare `import './globals.css'` unless the asset module is
 // declared. Vite resolves it at build time; the declaration is type-only.
 declare module '*.css'
+
+// `declare module '*?image'`: the build-time image pipeline. The `?image`
+// suffix on an image import is an explicit opt-in — it turns the import into
+// this optimized-asset OBJECT (srcSet variants + intrinsic size + a blur data
+// URI) instead of vite's plain hashed-URL string, so a bare image import keeps
+// its usual semantics. `<Image src={asset}>` consumes exactly this shape.
+declare module '*?image' {
+  const asset: {
+    readonly src: string
+    readonly width: number
+    readonly height: number
+    readonly blurDataURL: string
+    readonly srcSet: string
+    readonly sources: ReadonlyArray<{ readonly type: string; readonly srcSet: string }>
+  }
+  export default asset
+}

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

@@ -8,8 +8,9 @@ export default defineLocale<typeof en>()({
   'nav.home':     'Start',
   'nav.language': 'Sprache',
 
-  'hero.tagline': 'Ersetze diesen Hero-Text durch dein Nutzenversprechen.',
-  'hero.cta':     'Mehr erfahren →',
+  'hero.tagline':  'Ersetze diesen Hero-Text durch dein Nutzenversprechen.',
+  'hero.cta':      'Mehr erfahren →',
+  'hero.imageAlt': 'Abstrakte Verlaufsgrafik',
 
   'features.heading':     'Funktionen',
   'features.reactive':    '<strong>Reaktive Subscriptions.</strong> Server-Status streamt per WebSocket zu den Clients.',

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

@@ -10,8 +10,11 @@ export default defineCatalog({
   'nav.home':     'Home',
   'nav.language': 'Language',
 
-  'hero.tagline': 'Replace this hero copy with your value prop.',
-  'hero.cta':     'Learn more →',
+  'hero.tagline':  'Replace this hero copy with your value prop.',
+  'hero.cta':      'Learn more →',
+  // `alt` is an attribute, so the page reads this with `useT` (a string), not
+  // <T> (an element). Decorative-only images take alt="" instead.
+  'hero.imageAlt': 'Abstract gradient artwork',
 
   'features.heading':     'Features',
   'features.reactive':    '<strong>Reactive subscriptions.</strong> Server state streams to clients via WebSocket.',

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

@@ -10,6 +10,15 @@
 //      @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.
+//   3. the hero image renders as a <picture> with the pipeline's variants.
+//
+// WHY THE `?image` IMPORT IS MOCKED. `voltro test` runs vitest WITHOUT the
+// CLI's image plugin (it is a `voltro dev` / `voltro build` transform), so a
+// `?image` specifier resolves to a plain URL STRING under the unit runner —
+// <Image> would then fall back to the loader path and warn about the missing
+// intrinsic size. Substituting the asset OBJECT the pipeline produces keeps the
+// page code idiomatic (no hand-written width/height) and makes the <picture> /
+// blur / srcSet assertions below mean what they say.
 
 import { afterEach, describe, expect, test, vi } from 'vitest'
 import { act, createElement, type ReactNode } from 'react'
@@ -37,8 +46,27 @@ vi.mock('@voltro/i18n', () => ({
       c,
   T: ({ id, values }: { id: string; values?: Record<string, unknown> }) =>
     fill(catalogs[currentLocale]?.[id] ?? id, values),
+  // The string form, for message ids used as ATTRIBUTES (the image's `alt`).
+  useT: (id: string, values?: Record<string, unknown>): string =>
+    fill(catalogs[currentLocale]?.[id] ?? id, values),
 }))
 
+// What the `?image` pipeline hands <Image> at build time, in miniature: two
+// modern-format sources, a same-family fallback srcSet, the intrinsic size read
+// off the file, and the inlined blur placeholder.
+const HERO_ASSET = {
+  src: '/assets/hero.abc123.jpeg',
+  width: 1200,
+  height: 630,
+  blurDataURL: 'data:image/jpeg;base64,BLUR',
+  srcSet: '/assets/hero.640.jpeg 640w, /assets/hero.abc123.jpeg 1200w',
+  sources: [
+    { type: 'image/avif', srcSet: '/assets/hero.640.avif 640w, /assets/hero.1200.avif 1200w' },
+    { type: 'image/webp', srcSet: '/assets/hero.640.webp 640w, /assets/hero.1200.webp 1200w' },
+  ],
+} as const
+vi.mock('../assets/hero.jpg?image', () => ({ default: HERO_ASSET }))
+
 const { default: Index, meta, renderMode, interactive } = await import('./page')
 
 ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
@@ -108,3 +136,54 @@ describe('index — localized render', () => {
     expect(container.textContent).toContain('Bereit loszulegen?')
   })
 })
+
+describe('index — the hero image + the self-hosted font', () => {
+  test('renders a <picture> with one <source> per modern format, avif first', () => {
+    render(createElement(Index))
+    const picture = container.querySelector('picture')
+    expect(picture).toBeTruthy()
+    const types = Array.from(picture!.querySelectorAll('source')).map((s) => s.getAttribute('type'))
+    expect(types).toEqual(['image/avif', 'image/webp'])
+  })
+
+  test('the <img> carries the fallback srcSet + the intrinsic size off the asset', () => {
+    render(createElement(Index))
+    const img = container.querySelector('picture img') as HTMLImageElement
+    // width/height are NOT props on the page — they come off the imported
+    // asset, which is what reserves the box (CLS) without hand-written numbers.
+    expect(img.getAttribute('width')).toBe('1200')
+    expect(img.getAttribute('height')).toBe('630')
+    expect(img.getAttribute('srcset')).toBe(HERO_ASSET.srcSet)
+    expect(img.getAttribute('src')).toBe(HERO_ASSET.src)
+  })
+
+  test('priority makes it the LCP image: eager, not lazy', () => {
+    render(createElement(Index))
+    const img = container.querySelector('picture img') as HTMLImageElement
+    expect(img.getAttribute('loading')).toBe('eager')
+    expect(img.getAttribute('fetchpriority')).toBe('high')
+  })
+
+  test('the blur placeholder is painted behind it until it loads', () => {
+    render(createElement(Index))
+    const img = container.querySelector('picture img') as HTMLImageElement
+    expect(img.style.backgroundImage).toContain(HERO_ASSET.blurDataURL)
+  })
+
+  test('alt text is localized — it goes through useT, not <T>', () => {
+    currentLocale = 'de'
+    render(createElement(Index))
+    const img = container.querySelector('picture img') as HTMLImageElement
+    expect(img.getAttribute('alt')).toBe(de['hero.imageAlt'])
+    expect(img.getAttribute('alt')).not.toBe(en['hero.imageAlt'])
+  })
+
+  test('the hero heading references the declared family through its CSS variable', () => {
+    render(createElement(Index))
+    // `localFont('Geist')` maps the family declared in app.config.ts `fonts:`
+    // to the variable the generated shell defines. Asserting the VARIABLE (not
+    // a literal 'Geist') is the point: the slug rule stays the pipeline's.
+    const h1 = container.querySelector('main h1') as HTMLElement
+    expect(h1.style.fontFamily).toBe('var(--font-geist)')
+  })
+})

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

@@ -8,9 +8,17 @@
 // 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 { Image, localFont, type PageMeta } from '@voltro/web'
+import { T, useT } from '@voltro/i18n'
 import { getCatalog } from '../lib/locale'
+// The `?image` suffix opts this import into the BUILD-TIME pipeline: instead of
+// vite's plain hashed URL it resolves to an optimized-asset object — AVIF+WebP
+// variants at every ladder width up to the intrinsic 1200px plus a jpeg
+// fallback, the intrinsic width/height, and an inlined 16px blur data URI.
+// `voltro build` encodes them into dist/assets/ under content hashes (through a
+// persistent cache, so a rebuild re-encodes nothing); `voltro dev` transforms on
+// demand. Nothing here requires JS on the page — it renders as a <picture>.
+import hero from '../assets/hero.jpg?image'
 
 // Pre-render at build time. Removes the runtime dependency entirely
 // for plain-content pages — no rpc client, no react hydration. If you
@@ -32,14 +40,29 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
 const strong = (chunks: ReactNode): ReactNode => <strong>{chunks}</strong>
 const code = (chunks: ReactNode): ReactNode => <code>{chunks}</code>
 
+// The typed way to name a family declared in app.config.ts `fonts:` from TSX.
+// It is a pure NAME MAPPER — `{ variable: '--font-geist', fontFamily:
+// 'var(--font-geist)' }` — so it never has to be kept in sync with the slug
+// rule by hand. src/globals.css points the kit's `--font-sans` at the same
+// variable app-wide; this is the per-component form.
+const brand = localFont('Geist')
+
 export default function Index(): ReactNode {
+  // `alt` is an ATTRIBUTE, not children, so it needs a plain string — that is
+  // what `useT` is for; `<T>` returns an element and cannot be used here.
+  const heroAlt = useT('hero.imageAlt')
   return (
     <main>
       <section>
-        <h1>{{capProjectName}}</h1>
+        <h1 style={{ fontFamily: brand.fontFamily }}>{{capProjectName}}</h1>
         <p>
           <T id="hero.tagline" />
         </p>
+        {/* `priority` marks this the LCP image: eager load + high fetch
+          * priority instead of the lazy default. width/height/blur are NOT
+          * hand-written — they come off the imported asset, which is what
+          * reserves the box and keeps CLS at zero. */}
+        <Image src={hero} alt={heroAlt} priority sizes="(max-width: 900px) 100vw, 900px" />
         <a href="#features">
           <T id="hero.cta" />
         </a>

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

@@ -1,6 +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"]
+  "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. Ships the asset pipelines a marketing page actually needs: a local hero image through `?image` + `<Image>` (AVIF/WebP srcSet, inferred dimensions, blur placeholder) and a self-hosted woff2 declared under `fonts:` (hashed, size-adjusted fallback face, preload — no font CDN). Flip interactive: 'islands' for interactive pieces.",
+  "tags": ["web", "frontend", "landing", "marketing", "static", "i18n", "intl", "localization", "images", "fonts", "assets"]
 }

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.53.0",
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/ui-shadcn": "0.53.0",
-    "@voltro/web": "0.53.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.53.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.53.0",
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/ui-shadcn": "0.53.0",
-    "@voltro/web": "0.53.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.53.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,17 +12,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/ui-shadcn": "0.53.0",
-    "@voltro/web": "0.53.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.53.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,17 +12,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/ui-shadcn": "0.53.0",
-    "@voltro/web": "0.53.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.53.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-ssr-api/package.json

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.53.0",
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/ui-shadcn": "0.53.0",
-    "@voltro/web": "0.53.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.53.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-static-blog/package.json

@@ -12,18 +12,19 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/content": "0.53.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/content": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "effect": "^3.22.0",
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/web": "0.53.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.53.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

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

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.53.0",
-    "@voltro/cli": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/i18n": "0.53.0",
-    "@voltro/ui-shadcn": "0.53.0",
-    "@voltro/web": "0.53.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.53.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/mobile-app/package.json

@@ -4,20 +4,21 @@
   "private": true,
   "main": "expo-router/entry",
   "scripts": {
-    "start": "voltro codegen . && expo start",
-    "ios": "voltro codegen . && expo run:ios",
-    "android": "voltro codegen . && expo run:android",
-    "web": "voltro codegen . && expo start --web",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "codegen": "voltro codegen ."
+    "start": "voltro mobile codegen . && expo start",
+    "ios": "voltro mobile codegen . && expo run:ios",
+    "android": "voltro mobile codegen . && expo run:android",
+    "web": "voltro mobile codegen . && expo start --web",
+    "test": "voltro mobile codegen . && vitest run",
+    "typecheck": "voltro mobile codegen . && tsc --noEmit",
+    "codegen": "voltro mobile codegen .",
+    "links": "voltro mobile links ."
   },
   "dependencies": {
     "@react-native-async-storage/async-storage": "1.23.1",
     "@react-native-community/netinfo": "11.4.1",
-    "@voltro/client": "0.53.0",
-    "@voltro/react-native": "0.53.0",
-    "@{{projectName}}/api": "0.53.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/react-native": "0.54.0",
+    "@{{projectName}}/api": "0.54.0",
     "expo": "^52.0.0",
     "expo-constants": "~17.0.0",
     "expo-linking": "~7.0.0",
@@ -32,7 +33,7 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@vitest/coverage-v8": "^4.1.10",
-    "@voltro/cli": "0.53.0",
+    "@voltro/cli": "0.54.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/mobile-app/src/lib/deeplinks.ts

@@ -1,27 +1,39 @@
-// The app's deep-link table + a pure resolver.
+// The app's deep-link table — GENERATED, not hand-written.
 //
 // A deep link maps an inbound URL — a universal link (`https://…/orders/42`), a
 // custom-scheme URL (`{{appName}}://orders/42`), or a push payload's
-// `data.deepLink` — to an in-app navigation. `defineDeepLink` + the pure matcher
-// come from `@voltro/react-native`; this module is browser/RN-safe (no Metro, no
-// screens), which is exactly why it is unit-testable without a simulator.
+// `data.deepLink` — to an in-app navigation. Notice what is NOT in this file: a
+// list of links. `voltro mobile codegen` derives one link per Expo Router screen
+// under `src/app/`, because a screen's route path and a deep-link pattern are
+// the same path in two syntaxes (`app/orders/[id].tsx` ↔ `/orders/:id`). Add a
+// screen and its link exists.
 //
-// Declaration order wins in `dispatchDeepLink`, so list more-specific patterns
-// FIRST. The `navigate` callback is injected (the screen layer passes
-// expo-router's `router.push`), keeping this table pure + testable.
-import {
-  defineDeepLink,
-  dispatchDeepLink,
-  type DeepLinkDescriptor,
-} from '@voltro/react-native'
+// **When you need a link file.** Write a `*.deepLink.ts` (default-exporting
+// `defineDeepLink`) when a link needs something the derived one cannot do —
+// param coercion, an auth check, or a side effect before navigation:
+//
+//     // src/lib/invoice.deepLink.ts  — NOT under src/app/: Expo Router routes
+//     // every .ts/.tsx there, so a link file placed inside it ships a screen.
+//     import { router } from 'expo-router'
+//     import { defineDeepLink } from '@voltro/react-native'
+//
+//     export default defineDeepLink({
+//       pattern: '/invoices/:number',
+//       handler: ({ number }) => router.push(`/invoices/${number.padStart(6, '0')}`),
+//     })
+//
+// Declared links are matched BEFORE derived ones, so one for `/orders/:id`
+// replaces the screen-derived link for that pattern rather than racing it.
+//
+// This module stays a thin adapter on purpose: it is browser/RN-safe (no Metro,
+// no screens), which is what makes the routing unit-testable without a simulator.
+import { dispatchDeepLink, type DeepLinkDescriptor } from '@voltro/react-native'
+import { deepLinks } from '../../.framework/deepLinks.generated'
 
-/** Build the app's deep links against a navigate function (expo-router's `push`). */
+/** The app's deep links, bound to a navigate function (expo-router's `push`). */
 export const makeDeepLinks = (
   navigate: (href: string) => void,
-): ReadonlyArray<DeepLinkDescriptor> => [
-  defineDeepLink({ pattern: '/orders/:id', handler: ({ id }) => navigate(`/orders/${id}`) }),
-  defineDeepLink({ pattern: '/settings', handler: () => navigate('/settings') }),
-]
+): ReadonlyArray<DeepLinkDescriptor> => deepLinks(navigate)
 
 /**
  * Route an inbound URL through the link table. Returns `true` when a link