@squadbase/vantage-template 0.0.1

package/base-template/AGENTS.md

@@ -0,0 +1,339 @@
+# AGENTS.md — Vantage アプリの地図
+
+このファイルは、**Vantage(`@squadbase/vantage`)アプリを作るコーディングエージェント**が
+最初に読むための地図です。アプリ作者(= `index.tsx` を書く側)が守るべき規約・不変条件・
+最小レシピを 1 ページに集約しています。ここに書かれた規約だけで、最小のダッシュボードアプリを
+正しく組めます。
+
+> このファイルは **Vantage フレームワークが所有する正本**のコピーです。手で書き換えても、
+> `vantage upgrade` を実行するとフレームワーク同梱の正本から再同期されて上書きされます。
+> アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
+>
+> 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています。このファイルは
+> 「地図」、Skill は「手順書」という役割分担です。**配置済みの Skill を先に探す**手順は
+> 末尾の「さらに詳しく(同梱 Skill)」にあります。
+
+## Vantage とは
+
+設定ファイル不要(config-free)な React ダッシュボードフレームワーク。アプリ作者が書くのは
+`index.tsx`(と任意の追加ファイル)だけで、Vite・ルーティング・TanStack Query・Tailwind・
+UI キット・開発サーバー・API サーバー・ビルドはすべて Vantage が所有します。設定は
+「ファイル名の規約」で表現します。
+
+## 不変条件(破ると静かに壊れる)
+
+- **設定ファイルを作らない。** `vite.config.*`・`tailwind.config.*`・`postcss.config.*`・
+  `components.json`・`vantage.config.*` はすべて禁止。存在すると `vantage check` がエラーにする
+  (`FORBIDDEN_FILE`)。テーマ調整は `styles.css` のトークンで行う。
+- **import は必ず `@squadbase/vantage` のサブパス経由。** `@tanstack/*`・`@base-ui/react`・
+  `echarts`・`hono`・`vite`・`tailwindcss` を直接 import しない。`lucide-react` のアイコンだけは
+  直接 import してよい。
+- **クライアントコードは `server/` を import してはならない。** 違反は `CLIENT_IMPORTS_SERVER`
+  エラー(静的にもビルド時にも弾かれる)。共有したいコードは `lib/` に置く。
+- **クライアントに届く env は `PUBLIC_` 接頭辞のものだけ。** `import.meta.env.PUBLIC_FOO`。
+  それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。シークレットは
+  `ApiContext.env`(server/ 内)にだけ届く。
+- **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。任意の CLI
+  コマンド、または `vantage upgrade` で再生成される。
+- **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
+  ため、変数・関数呼び出し・テンプレート補間は使わない。`page` エクスポートはランタイムでは
+  読まれない。
+
+## import サブパスの地図
+
+| import 元 | 提供するもの |
+| --- | --- |
+| `@squadbase/vantage` | `definePage`(ページ設定) |
+| `@squadbase/vantage/router` | `Link`・`Outlet`・`useParams`・`useSearch`・`useNavigate`・`redirect`・`notFound`・`useRoutes`・`useCurrentRoute`・`useSearchParam`・`useSearchState` |
+| `@squadbase/vantage/query` | `useApiQuery`・`useApiMutation`・`apiJson`・`apiFetch`・`apiUrl`・`ApiError`、ほか `useQuery`/`useMutation` など TanStack Query の再エクスポート |
+| `@squadbase/vantage/ui` | shadcn/ui(Base UI バリアント)プリミティブ(`Button`・`Loading`・`ErrorState`・`Empty` ほか) |
+| `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
+| `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
+| `@squadbase/vantage/server` | `ApiContext`・`ApiHandler`・`HttpError`・`isHttpError`・`json`(server/ 側でのみ使う) |
+
+## モードは 2 つ、切り替えるのは `server/` の有無だけ
+
+`server/` ディレクトリがあれば **fullstack**、無ければ **SPA**。`vantage-manifest.json` の
+`mode` はここから自動で決まり、手で書く設定は無い。**SPA から始めて fullstack へ「昇格」する
+必要はない** ― テンプレートから始めた場合は最初から `server/` があり、その時点で fullstack。
+下の 2 節は段階ではなく、いま自分がどちらにいるかを確かめるための地図として読む。
+
+- `server/` が**ある** → 「API を持つ(fullstack モード)」を見る。データは自前の `/api/*` から
+  `useApiQuery` で取る。
+- `server/` が**無い** → 「最小アプリ(2 ファイル)」の構成。外部 API を直接叩くなら `useQuery`。
+  自前の API が要るようになったら `server/api/*.ts` を足すだけでよい(設定変更は不要)。
+
+## 最小アプリ(2 ファイル)
+
+`package.json` と `index.tsx` の 2 ファイルだけで動く。
+
+`package.json`:
+
+```json
+{
+  "name": "my-dashboard",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vantage dev",
+    "build": "vantage build",
+    "preview": "vantage preview",
+    "check": "vantage check",
+    "routes": "vantage routes"
+  },
+  "dependencies": {
+    "@squadbase/vantage": "^0.2.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  }
+}
+```
+
+`index.tsx`(ルートのデフォルトエクスポートが `/` ページになる):
+
+```tsx
+export default function Dashboard() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-semibold">Dashboard</h1>
+    </main>
+  )
+}
+```
+
+```bash
+pnpm install
+pnpm dev      # → http://localhost:5173(HMR)
+pnpm check    # 静的診断(エラーがあれば exit 1)
+pnpm routes   # ページ/API の URL マップ
+```
+
+`server/` ディレクトリが無いので、この構成は **SPA モード**。
+
+## ルーティング規約(ファイル名 → ルート)
+
+ルートディレクトリ直下の `.tsx`/`.jsx` がそのままページになる。各ページは**デフォルト
+エクスポートの React コンポーネントが必須**(無いと `MISSING_DEFAULT_EXPORT`)。
+
+| ファイル | ルート |
+| --- | --- |
+| `index.tsx` | `/` |
+| `monthly-analysis.tsx` | `/monthly-analysis` |
+| `sales/index.tsx` | `/sales` |
+| `sales/[customerId].tsx` | `/sales/:customerId`(動的パラメータ) |
+| `_layout.tsx` | そのディレクトリ配下を包むネストレイアウト(`Outlet` で子を描く) |
+| `_404.tsx` | Not Found ページ |
+| `_error.tsx` | ルートが throw したときのエラーページ |
+
+`components/`・`hooks/`・`lib/`・`server/`・`public/` はルート走査の対象外(ページにならない)。
+
+```tsx
+import { definePage } from "@squadbase/vantage"
+
+// title は document.title、navLabel は useRoutes() で組むナビの表示名(既定は title)
+export const page = definePage({ title: "Monthly Analysis · Acme", navLabel: "Monthly" })
+
+export default function MonthlyAnalysis() {
+  return <main className="p-6">…</main>
+}
+```
+
+### ナビはルート一覧から組む
+
+`useRoutes()` がページルート一覧(スキャン順)を返すので、リンク配列を手で持たない。
+`useCurrentRoute()` は現在のルート(404 なら `undefined`)。
+
+```tsx
+import { Link, useCurrentRoute, useRoutes } from "@squadbase/vantage/router"
+
+// 動的ルートは URL が定まらないので外す。label は navLabel → title → path の順
+const routes = useRoutes().filter((r) => !r.dynamic)
+const current = useCurrentRoute()
+
+routes.map((r) => (
+  <Link key={r.path} to={r.to} activeClassName="font-semibold">
+    {r.label}
+  </Link>
+))
+```
+
+`RouteInfo`: `path`(`/sales/:id`)・`to`(`/sales/$id`)・`params`・`dynamic`・`index`・`label`・
+`title`・`description`・`navLabel`。
+
+### フィルタ状態は URL に置く
+
+リロードで消えず、URL をそのまま共有できる。`useState` と同じ形。
+
+```tsx
+import { useSearchParam, useSearchState } from "@squadbase/vantage/router"
+
+const [region, setRegion] = useSearchParam("region", "all")   // 常に string
+const [segments, setSegments] = useSearchState<string[]>("segments", []) // JSON になる値
+```
+
+デフォルト値(または `null`)を書くとキーは URL から消える。履歴は既定で `replace`
+(`{ replace: false }` で push)。
+
+### 動的パラメータの「3 つの綴り」を同期させる
+
+崩すと静かにマッチしなくなる不変条件:
+
+- ファイル名 `sales/[customerId].tsx`
+- 表示ルート `/sales/:customerId`
+- リンクトークン `to="/sales/$customerId"` + `params={{ customerId }}`
+
+```tsx
+import { Link, useParams } from "@squadbase/vantage/router"
+
+<Link to="/sales/$customerId" params={{ customerId: row.id }}>{row.name}</Link>
+
+// 詳細ページ側で取り出す
+const { customerId } = useParams()
+```
+
+## データ取得(server を持たない fetch)
+
+外部 API を叩くだけなら `server/` は不要。`@squadbase/vantage/query` の `useQuery` を使う:
+
+```tsx
+import { useQuery } from "@squadbase/vantage/query"
+import { Loading, ErrorState } from "@squadbase/vantage/ui"
+
+const q = useQuery({ queryKey: ["stats"], queryFn: () => fetch("/…").then((r) => r.json()) })
+if (q.isPending) return <Loading />
+if (q.isError) return <ErrorState message={(q.error as Error).message} />
+```
+
+`QueryClient` は Vantage が 1 つだけ管理する(staleTime 30s・retry 1・
+refetchOnWindowFocus false・networkMode "always")。挙動を変えたいときはクエリ側のオプションで
+上書きする。
+自分の `server/api` を叩くときは `useQuery` ではなく `useApiQuery`(→「API を持つ(fullstack
+モード)」)。
+
+## API を持つ(fullstack モード)
+
+**`server/` ディレクトリがあれば fullstack モード**(無いアプリに足せば、その時点で切り替わる)。
+`server/api/**` の各ファイルが API ルートになる。
+
+`server/api/monthly-analysis.ts` → `GET /api/monthly-analysis`:
+
+```ts
+import type { ApiContext } from "@squadbase/vantage/server"
+import { HttpError } from "@squadbase/vantage/server"
+
+export async function GET({ params, env }: ApiContext) {
+  if (!env.API_KEY) throw new HttpError(500, "API_KEY missing")
+  return Response.json({ ok: true })
+}
+```
+
+- API モジュールは**大文字の HTTP メソッド**(`GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`)を
+  エクスポートする。それ以外の名前は `INVALID_API_EXPORT` エラー。
+- 動的 API も `[id].ts` 記法: `server/api/customers/[id].ts` → `GET /api/customers/:id`。
+  `params.id` で取り出す(`noUncheckedIndexedAccess` が効くので narrowing が要る)。
+- **クライアントに見せたいエラーは `HttpError(status, msg)` を throw する。** それ以外の throw は
+  ログに記録され汎用の 500 に丸められる。
+- **シークレットは `ApiContext.env` にだけ届く**(クライアントには決して届かない)。
+
+クライアント側からは `useApiQuery` で `/api/*` を叩く。ベース URL の解決・JSON パース・
+非 2xx の `ApiError` 化・クエリキー(`["api", url]`)が入っている:
+
+```tsx
+import { useApiQuery, useApiMutation } from "@squadbase/vantage/query"
+
+const q = useApiQuery<Customer>(`/api/customers/${customerId}`)
+if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージ
+
+// クエリ文字列は search で。undefined の項目は落ちる
+const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
+
+// 書き込み。変数がそのまま JSON ボディになる
+const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST" })
+```
+
+`ApiError` は `message`・`status`・`body`・`requestId` を持つ。hook が使えない場所では
+`apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。
+
+## 環境変数
+
+- **クライアントで読めるのは `import.meta.env.PUBLIC_*` と `MODE`/`DEV`/`PROD`/`SSR`/`BASE_URL`
+  のみ。** `VITE_` 系の公開 API は無い。
+- サーバー側のシークレットは `ApiContext.env.MY_SECRET` で読む(`server/` 内のみ)。
+
+## 組み込み UI / コンポーネントの入口
+
+- **プリミティブ**は `@squadbase/vantage/ui` から import する(`Button`・`Loading`・
+  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。
+- **複合パーツ**は `@squadbase/vantage/components` から(`PageShell`・`DashboardCardPreset`・
+  `DataTablePreset`・`EChart` ほか)。
+- **どの名前が import 可能か / props の詳細は `vantage docs` で引く。** ガイドとコンポーネント
+  リファレンスはパッケージに同梱されていて、オフラインでも読める(→「ドキュメントを引く」)。
+  **名前が分からないとき**はやりたいことで `vantage search` する(→ 同節)。
+- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui|block` は
+  ソースを手元にコピーして**改造したいとき専用**のコマンドで、取り出せるのは
+  `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
+  `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
+
+## ドキュメントを引く(`vantage docs` / `vantage search`)
+
+```bash
+vantage docs                  # 全ページの一覧(ガイド + コンポーネント)
+vantage docs button           # 1 ページ表示(短縮名。ui/button に解決される)
+vantage docs parts/data-table # 完全な slug でも引ける
+vantage docs data-table --json  # { slug, title, description, section, content }
+vantage docs --all            # 全ページを連結(まとめて読み込む用)
+vantage docs routing --lang en  # 英語版(既定は ja)
+```
+
+props の表・使用例・落とし穴はコンポーネントのページに載っている。**推測で props を書く前に
+`vantage docs <name>` を引くこと。** 本文中のリンクは slug なので、`[DataTable](parts/data-table)`
+は `vantage docs parts/data-table` で開ける。
+
+**名前が分からないときは検索する。** 対象は `vantage docs` と同じ同梱ドキュメント。
+
+```bash
+vantage search 期間を選ぶ UI が欲しい       # 自然言語(BM25)。やりたいことで引く
+vantage search "enable[A-Z]\w+" --regex    # 正規表現で props を横断(行番号付き)
+vantage search テーブル --limit 5 --json    # 機械可読(slug + score + snippet)
+```
+
+結果の slug はそのまま `vantage docs <slug>` に渡せる。
+
+## 検証・ビルド・プレビュー
+
+```bash
+pnpm check     # 静的診断(禁止ファイル・ルート衝突・境界・API export・env 誤用)
+pnpm routes    # ページ + API の URL マップ
+pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
+pnpm preview   # 本番ビルドをローカル実行
+```
+
+`vantage-manifest.json` の `mode`(`spa` / `fullstack`)は `server/` の有無から自動で決まる
+(手で書かない)。`vantage routes` は `--pages` / `--apis` で片側だけに絞れ、`--detail` を足すと
+各ルートの静的な仕様(ページ: パスパラメータ + `definePage` のメタ / API: メソッド・query・
+body・レスポンスの status と形)まで出る。`vantage check --json` / `vantage routes --json` は
+エージェント向けの機械可読出力。`console.*` とランタイムエラーは開発ターミナルに `[browser:…]` として転送される。
+
+## さらに詳しく(同梱 Skill)
+
+- **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
+- **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
+- **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
+
+手順書の本体は `SKILL.md` というファイルで、置き場所はアプリによって違う(ルート直下・
+`.claude/skills/`・`.squadbase/skills/` など)。**探す必要はない ― CLI が探す:**
+
+```bash
+vantage add skill          # 同梱 skill の一覧と、それぞれの配置場所
+```
+
+配置済みならその場所が出るので、その `SKILL.md` を読む。`not placed` のものだけ配置する:
+
+```bash
+vantage add skill --all                        # 配置済みはスキップ(場所を報告するだけ)
+vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定はルート直下)
+```
+
+`add skill` はプロジェクト内を走査してから動くので、**再実行しても二重に配置されない**。
+配置済みのコピーを新しいバージョンに更新したいときだけ `--force` を付ける(見つかった場所を
+そのまま書き換える)。

package/base-template/_404.tsx

@@ -0,0 +1,18 @@
+import { Link } from "@squadbase/vantage/router"
+import { Button, Empty } from "@squadbase/vantage/ui"
+
+export default function NotFound() {
+  return (
+    <div className="flex min-h-[50vh] items-center justify-center">
+      <Empty
+        title="404 — Page not found"
+        description="The page you are looking for doesn't exist or was moved."
+        action={
+          <Link to="/">
+            <Button>Go home</Button>
+          </Link>
+        }
+      />
+    </div>
+  )
+}

package/base-template/_error.tsx

@@ -0,0 +1,14 @@
+import { Button, ErrorState } from "@squadbase/vantage/ui"
+
+export default function RouteError({ error }: { error: unknown }) {
+  const message = error instanceof Error ? error.message : String(error)
+  return (
+    <div className="flex min-h-[50vh] items-center justify-center">
+      <ErrorState
+        title="This page failed to render"
+        message={message}
+        action={<Button onClick={() => window.location.reload()}>Reload</Button>}
+      />
+    </div>
+  )
+}

package/base-template/_gitignore

@@ -0,0 +1,5 @@
+dist/
+node_modules/
+.vantage/
+*.tsbuildinfo
+*.log

package/base-template/_layout.tsx

@@ -0,0 +1,60 @@
+import type { ComponentProps } from "react"
+import { SquadbaseProvider } from "@squadbase/react"
+import { Link, Outlet, useCurrentRoute, useRoutes } from "@squadbase/vantage/router"
+import { AppShell } from "@squadbase/vantage/components"
+import type { NavGroup } from "@squadbase/vantage/components"
+
+import { UserCard } from "./components/user-card"
+
+/**
+ * `AppShell` is router-agnostic and renders nav entries through whatever
+ * component it is handed, using an `href` prop. Adapt it to the Vantage router
+ * so navigation stays client-side.
+ */
+function RouterLink({ href, ...props }: { href: string } & ComponentProps<"a">) {
+  return <Link to={href} {...props} />
+}
+
+/**
+ * The nav *is* the route list — adding a page file puts it in the nav, with no
+ * second list to keep in sync. Dynamic routes (`sales/[id].tsx`) have no single
+ * URL, so they are filtered out; `route.label` resolves `navLabel` → `title` →
+ * path, so shorten a long page title with `definePage({ navLabel })`.
+ */
+function useNavGroups(): NavGroup[] {
+  const routes = useRoutes()
+  const current = useCurrentRoute()
+  return [
+    {
+      label: "Pages",
+      items: routes
+        .filter((route) => !route.dynamic)
+        .map((route) => ({
+          label: route.label,
+          href: route.to,
+          isActive: route.path === current?.path,
+        })),
+    },
+  ]
+}
+
+/**
+ * The root layout is the only place an app-wide provider can go — Vantage owns
+ * the React root, so there is no `main.tsx` to wrap. `SquadbaseProvider` supplies
+ * the signed-in user to `useUser()`; the QueryClient provider is already
+ * installed by the runtime.
+ */
+export default function RootLayout() {
+  return (
+    <SquadbaseProvider>
+      <AppShell
+        variant="header"
+        groups={useNavGroups()}
+        actions={<UserCard />}
+        linkComponent={RouterLink}
+      >
+        <Outlet />
+      </AppShell>
+    </SquadbaseProvider>
+  )
+}

package/base-template/components/user-card.tsx

@@ -0,0 +1,132 @@
+import { useUser } from "@squadbase/react"
+import type { User } from "@squadbase/react"
+import { UserIcon } from "lucide-react"
+import {
+  Badge,
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+  cn,
+} from "@squadbase/vantage/ui"
+
+/**
+ * Squadbase-authenticated user chip for the app shell.
+ *
+ * The Vantage UI kit has no `Avatar`, so the initials bubble is inlined here —
+ * it is a handful of classes and only ever used by this component.
+ */
+function Avatar({ user, className }: { user: User; className?: string }) {
+  const fullName = `${user.firstName} ${user.lastName}`
+  const initials = `${user.firstName.charAt(0)}${user.lastName.charAt(0)}`
+  return (
+    <span
+      className={cn(
+        "flex shrink-0 items-center justify-center overflow-hidden rounded-full bg-muted font-medium",
+        className,
+      )}
+    >
+      {user.iconUrl ? (
+        <img src={user.iconUrl} alt={fullName} className="size-full object-cover" />
+      ) : (
+        initials
+      )}
+    </span>
+  )
+}
+
+function DetailRow({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div>
+      <p className="text-sm text-muted-foreground">{label}</p>
+      <div className="font-medium">{children}</div>
+    </div>
+  )
+}
+
+function UserInfo({ user }: { user: User }) {
+  const fullName = `${user.firstName} ${user.lastName}`
+  const rolesHref = navigator.language.startsWith("ja")
+    ? "https://www.squadbase.dev/ja/docs/access-control#プロジェクトロール"
+    : "https://www.squadbase.dev/docs/access-control#project-roles"
+
+  return (
+    <Dialog>
+      <DialogTrigger
+        render={
+          <button className="flex w-full items-center gap-3 rounded-md p-2 text-left hover:bg-sidebar-accent" />
+        }
+      >
+        <Avatar user={user} className="size-9 text-sm" />
+        <span className="flex flex-col overflow-hidden">
+          <span className="truncate text-sm font-medium">{fullName}</span>
+          <span className="truncate text-xs text-muted-foreground">{user.email}</span>
+        </span>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>User Details</DialogTitle>
+        </DialogHeader>
+        <div className="flex flex-col items-center gap-4">
+          <Avatar user={user} className="size-20 text-2xl" />
+          <div className="w-full space-y-4">
+            <DetailRow label="Name">{fullName}</DetailRow>
+            <DetailRow label="Username">{user.username}</DetailRow>
+            <DetailRow label="Email">{user.email}</DetailRow>
+            <div>
+              <div className="flex items-center justify-between">
+                <p className="text-sm text-muted-foreground">Project Roles</p>
+                <a
+                  href={rolesHref}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-xs text-muted-foreground underline underline-offset-4 hover:text-primary/80"
+                >
+                  Learn more
+                </a>
+              </div>
+              {user.roles.length > 0 ? (
+                <div className="mt-2 flex flex-wrap gap-1">
+                  {user.roles.map((role) => (
+                    <Badge key={role} variant="outline">
+                      {role}
+                    </Badge>
+                  ))}
+                </div>
+              ) : (
+                <p className="mt-2 text-sm text-muted-foreground">No roles assigned</p>
+              )}
+            </div>
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+function UserInfoFallback() {
+  return (
+    <div className="flex w-full items-center gap-3 rounded-md p-2">
+      <span className="flex size-9 shrink-0 items-center justify-center rounded-full bg-muted">
+        <UserIcon className="size-4 text-muted-foreground" />
+      </span>
+      <div className="flex flex-col overflow-hidden">
+        <span className="truncate text-sm font-medium text-muted-foreground">Guest</span>
+        <span className="truncate text-xs text-muted-foreground">
+          Unable to retrieve user information
+        </span>
+      </div>
+    </div>
+  )
+}
+
+export function UserCard() {
+  const userState = useUser()
+
+  if (userState.status === "success") {
+    return <UserInfo user={userState.data} />
+  }
+
+  return <UserInfoFallback />
+}

package/base-template/index.tsx

@@ -0,0 +1,59 @@
+import { definePage } from "@squadbase/vantage"
+import {
+  DashboardCardPreset,
+  PageShell,
+  PageShellContent,
+  PageShellDescription,
+  PageShellHeader,
+  PageShellHeading,
+  PageShellTitle,
+  Placeholder,
+} from "@squadbase/vantage/components"
+
+export const page = definePage({
+  title: "Dashboard",
+  description: "Sample data — replace with your own to get started.",
+  navLabel: "Home",
+})
+
+const METRICS = [
+  { label: "Metric 1", value: "1,234" },
+  { label: "Metric 2", value: "5,678" },
+  { label: "Metric 3", value: "90.1%" },
+  { label: "Metric 4", value: "$12.3k" },
+]
+
+const CHARTS = ["Chart 1", "Chart 2"]
+
+export default function HomePage() {
+  return (
+    <PageShell>
+      <PageShellHeader>
+        <PageShellHeading>
+          <PageShellTitle>Dashboard</PageShellTitle>
+          <PageShellDescription>
+            Sample data — replace with your own to get started.
+          </PageShellDescription>
+        </PageShellHeading>
+      </PageShellHeader>
+
+      <PageShellContent>
+        <section className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-4">
+          {METRICS.map((metric) => (
+            <DashboardCardPreset key={metric.label} title={metric.label}>
+              <Placeholder className="text-2xl font-bold">{metric.value}</Placeholder>
+            </DashboardCardPreset>
+          ))}
+        </section>
+
+        <section className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+          {CHARTS.map((title) => (
+            <DashboardCardPreset key={title} title={title}>
+              <Placeholder className="h-64 w-full" />
+            </DashboardCardPreset>
+          ))}
+        </section>
+      </PageShellContent>
+    </PageShell>
+  )
+}

package/base-template/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "vibe-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vantage dev",
+    "build": "vantage build",
+    "start": "node dist/server/index.mjs",
+    "preview": "vantage preview",
+    "check": "vantage check",
+    "routes": "vantage routes"
+  },
+  "dependencies": {
+    "@squadbase/react": "^0.0.1",
+    "@squadbase/vantage": "^0.2.3",
+    "date-fns": "^4.1.0",
+    "lucide-react": "^0.468.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "typescript": "~5.7.0"
+  }
+}

package/base-template/server/api/health.ts

@@ -0,0 +1,12 @@
+import type { ApiContext } from "@squadbase/vantage/server"
+
+/**
+ * `GET /api/health` — the seed endpoint that puts this app in fullstack mode.
+ *
+ * The presence of any `server/api/**` file is what makes Vantage build a server
+ * bundle; delete this directory and the app builds as a pure SPA instead.
+ * Secrets live on `ctx.env` and never reach the client bundle.
+ */
+export async function GET(_ctx: ApiContext) {
+  return Response.json({ status: "ok" })
+}

package/base-template/squadbase.yml

@@ -0,0 +1,5 @@
+# squadbase.yml
+version: "1"
+build:
+  framework: squadbase-vantage
+  runtime: node20