@squadbase/vantage

Data dashboard framework for Squadbase Editor — Vite-powered, config-free, one-file first.

You write index.tsx. Vantage owns routing, React, TanStack Query, Tailwind v4, the UI kit, the dev server, the optional API server, and the build. There is no config file.

Status: prototype (v0.5.3). APIs may still change between releases.

Install

npm install @squadbase/vantage
# or: pnpm add @squadbase/vantage

react and react-dom (>=18.2) are peer dependencies — install them if your project doesn't have them yet.

Quick start

Create a single index.tsx at your project root. The default-exported component becomes the / route:

// index.tsx
export default function Dashboard() {
  return (
    <main className="p-6">
      <h1 className="text-2xl font-semibold">Dashboard</h1>
    </main>
  );
}

Add scripts to your package.json so the CLI runs with the local binary on PATH, then start the dev server:

{
  "scripts": {
    "dev": "vantage dev",
    "build": "vantage build",
    "preview": "vantage preview"
  }
}

npm run dev        # → http://localhost:5173 (HMR + optional API)

Prefer a one-off invocation? Use pnpm exec vantage dev or npx vantage dev — a bare vantage dev only works from inside an npm script, where node_modules/.bin is on PATH.

CLI

| Command | What it does | |---|---| | vantage dev | Dev server (HMR + optional API). Default :5173 | | vantage build | Production build → dist/ (client + optional server + vantage-manifest.json) | | vantage preview | Run the production build locally | | vantage check | Static diagnostics (routes, boundaries, forbidden files). Exit 1 on error | | vantage routes | Print the page + API URL map (--pages | --apis for one side, --detail for each route's spec) | | vantage add <kind> <name> | Scaffold a page | api, or copy an editable ui | block, agent skill | agents file | | vantage docs [name] | Print the bundled guide + component reference (--list, --all, --json, --lang) | | vantage search <query> | Search that same reference by meaning (BM25) or by --regex (--limit, --json, --lang) | | vantage doctor | Report environment / project health | | vantage upgrade | Regenerate the .vantage/ artifacts |

Growing past one file

Vantage discovers structure from the filesystem — no config, no route table:

• Pages — any *.tsx with a default export becomes a route (sales/index.tsx → /sales, sales/[customerId].tsx → /sales/:customerId).
• Layouts — _layout.tsx wraps its directory; _404.tsx / _error.tsx handle not-found and errors.
• API — add server/api/** handlers to enable a backend; they run identically in dev and in the production build.
• Styling — Tailwind v4 works out of the box; drop in a styles.css.
• Hooks over that structure — useRoutes() / useCurrentRoute() build a nav from the file system, useSearchParam keeps filter state in the URL, and useApiQuery / useApiMutation call server/api with JSON and errors handled.

Import only from the curated @squadbase/vantage subpaths (/query, /router, /ui, /components, /markdown, /server); the internally-managed stack (TanStack, Base UI, ECharts, Hono, Vite) is not imported directly.

Working with coding agents

The reference an agent needs ships inside the package, so it never has to guess a prop name or reach for the network:

npx vantage docs                  # every guide + component page, offline
npx vantage docs button --json    # one page, machine-readable
npx vantage search "date range"   # find the right component by meaning
npx vantage add agents            # drop an AGENTS.md map into your project
npx vantage add skill             # list the bundled skills and where they sit
npx vantage add skill --all --dir .claude/skills   # install the Claude Code skills for Vantage

add skill scans the project first, so skills that are already placed — wherever they live — are skipped with their location reported instead of copied a second time.

vantage upgrade re-syncs AGENTS.md when you update the package.

Documentation

Full guides live in the Vantage docs (bilingual — English under docs/content/en, Japanese under docs/content).

License

MIT © Squadbase