# ViraStack Start — TanStack Start Edition

> Premium TanStack Start + React 19 + Tailwind CSS 4 boilerplate focused on clean architecture, UI/UX, and agent-ready developer experience. Auth, database/ORM, i18n, and testing are intentionally omitted — bring the solution that fits your project.

Built on TanStack Router file-based routing with type-safe loaders, nested layouts, and SSR via TanStack Start. UI primitives use **Base UI** (unstyled, accessible) styled with Tailwind CSS 4 design tokens. State is split by job: TanStack Query for server state, Zustand for client state, `nuqs` for URL state. Forms use React Hook Form + Zod. The home route renders a deletable `features/landing` demo that follows the canonical ViraStack feature tree. **ViraStack AI** (`@virastack/ai`) adds agent rules on scaffold; design skills come from [emilkowalski/skills](https://github.com/emilkowalski/skills) and [make-interfaces-feel-better](https://github.com/jakubkrehel/make-interfaces-feel-better).

- Tech stack: TanStack Start, TanStack Router, React 19, Tailwind CSS 4, TypeScript (strict + `noUncheckedIndexedAccess`), Node.js `>=20.9`
- UI: Base UI, Framer Motion, Sonner, Lucide React, `next-themes`, `class-variance-authority`
- Data & state: TanStack Query 5, Zustand, `nuqs`
- Forms: React Hook Form + Zod (+ `@hookform/resolvers`)
- API: Native `fetch` wrapper in `src/lib/api.ts` (`ApiError` with `message`, `status`, `data`); Axios is optional, not installed
- Env: Hand-rolled Zod schema in `src/env.ts` (`VITE_*` public vars)
- Tooling: ESLint 9, Prettier 3, Husky, Knip, Commitlint, Changesets, Vite 8
- Quality scripts: `pnpm typecheck`, `pnpm lint` / `lint:ci`, `pnpm knip`, `pnpm build`
- ViraStack AI (via `npx @virastack/ai init`): `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, `docs/*`
- Not included by default: Auth, DB/ORM, i18n, test runner, CSP

## Docs
- [Repository (GitHub)](https://github.com/virastack/start): CLI and templates
- [README](https://github.com/virastack/start/tree/main/templates/tanstack): Features, structure, and conventions
- [Architecture guide](https://github.com/virastack/ai/blob/main/templates/core/docs/architecture-guide.md): Placement rules and import conventions
- [Product docs](https://virastack.com/start/docs): ViraStack Start documentation
- [Start llms-full.txt](https://virastack.com/start/llms-full.txt): CLI flags and template map for agents
- [Ecosystem llms.txt](https://virastack.com/llms.txt): All ViraStack products

## Key Files & Entry Points
- [`src/routes/__root.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/routes/__root.tsx): Root route, document shell, providers, SEO head
- [`src/routes/index.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/routes/index.tsx): Home route → `<LandingPage />`
- [`src/routes/robots[.]txt.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/routes/robots%5B.%5Dtxt.ts): Dynamic robots.txt from `siteConfig`
- [`src/routes/sitemap[.]xml.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/routes/sitemap%5B.%5Dxml.ts): Dynamic sitemap from `siteConfig`
- [`src/routes/site[.]webmanifest.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/routes/site%5B.%5Dwebmanifest.ts): Dynamic web manifest from `siteConfig`
- [`src/start.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/start.ts): Global request middleware (baseline security headers)
- [`src/router.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/router.tsx): Router factory + TanStack Query SSR integration
- [`src/env.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/env.ts): Zod-validated environment schema (`VITE_*` public vars)
- [`src/config/site.config.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/config/site.config.ts): Site config (name, URL, links)
- [`src/config/seo.config.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/config/seo.config.ts): Default SEO meta helpers
- [`src/lib/api.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/lib/api.ts): Native `fetch` wrapper with retry & typed `ApiError`
- [`src/lib/query-client.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/lib/query-client.ts): QueryClient factory & defaults
- [`src/providers/Providers.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/providers/Providers.tsx): App-wide providers (Theme, Nuqs, Toaster)
- [`vite.config.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/vite.config.ts): Vite + TanStack Start + Tailwind

## Landing Feature (demo — delete when building)
Canonical tree under `src/features/landing/`. Home route composes `LandingPage`.

- [`src/features/landing/index.ts`](https://github.com/virastack/start/blob/main/templates/tanstack/src/features/landing/index.ts): Public export (`LandingPage`)
- [`src/features/landing/components/LandingPage.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/features/landing/components/LandingPage.tsx): Page composition (Header + sections + Footer)
- [`src/features/landing/components/Hero.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/features/landing/components/Hero.tsx): Hero section
- [`src/features/landing/components/Features.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/features/landing/components/Features.tsx): Feature grid
- [`src/features/landing/components/Showcase.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/features/landing/components/Showcase.tsx): Stack demos host (Query, Zustand, forms, nuqs)
- [`src/features/landing/components/UsersDemo.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/features/landing/components/UsersDemo.tsx): TanStack Query + `nuqs` demo
- [`src/features/landing/components/CartDemo.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/features/landing/components/CartDemo.tsx): Zustand demo
- [`src/features/landing/components/ProjectFormDemo.tsx`](https://github.com/virastack/start/blob/main/templates/tanstack/src/features/landing/components/ProjectFormDemo.tsx): RHF + Zod demo

Quick start: delete `src/features/landing`, replace `src/routes/index.tsx`, keep `components/layout` if you still want chrome.

## UI & Shared Layers
- [`src/components/ui`](https://github.com/virastack/start/tree/main/templates/tanstack/src/components/ui): Base UI primitives (Button, Input, Field, Dialog, Tabs, Skeleton, Label, Avatar, Table)
- [`src/components/layout`](https://github.com/virastack/start/tree/main/templates/tanstack/src/components/layout): Header / Footer (reusable; Header accepts optional `links`)
- [`src/components/shared`](https://github.com/virastack/start/tree/main/templates/tanstack/src/components/shared): Cross-feature components (ThemeToggle, NotFound, DefaultCatchBoundary)
- [`src/hooks`](https://github.com/virastack/start/tree/main/templates/tanstack/src/hooks), [`src/stores`](https://github.com/virastack/start/tree/main/templates/tanstack/src/stores), [`src/schemas`](https://github.com/virastack/start/tree/main/templates/tanstack/src/schemas): Shared barrels (promote via Rule of Three)
- [`src/helpers`](https://github.com/virastack/start/tree/main/templates/tanstack/src/helpers): Shared helpers
- [`src/styles/tailwind.css`](https://github.com/virastack/start/blob/main/templates/tanstack/src/styles/tailwind.css): Tailwind v4 entry + design tokens
- Assets: [`public/logo.webp`](https://github.com/virastack/start/blob/main/templates/tanstack/public/logo.webp), [`public/og.png`](https://github.com/virastack/start/blob/main/templates/tanstack/public/og.png), [`public/favicon.ico`](https://github.com/virastack/start/blob/main/templates/tanstack/public/favicon.ico)

## Customization & Imports
- Search the project for `FIXME:` (site config, auth attachment on the API client).
- Prefer short path aliases: `@/ui`, `@/hooks`, `@/schemas`, `@/layout` over long forms. Prefer feature-local imports under `@/features/[feature]/…` for demo-scoped code.
- Default scope is `features/[feature]/` — promote to global `src/` only when a second feature needs it. No cross-feature imports.

## ViraStack AI
- Install or refresh: `npx @virastack/ai init --force`
- `AGENTS.md`: Agent operating guide (all agents)
- `CLAUDE.md`: Claude Code entry point (`@AGENTS.md`)
- `.cursor/rules/*.mdc`: Scoped coding rules (Cursor auto-loads)
- `docs/architecture-guide.md`, `docs/MEMORIES.md`: Architecture and project memory
- Skills: [emilkowalski/skills](https://github.com/emilkowalski/skills) (7 design-engineering skills) + [make-interfaces-feel-better](https://github.com/jakubkrehel/make-interfaces-feel-better)
- Package: [`@virastack/ai`](https://github.com/virastack/ai)

## External References
- [TanStack Start Docs](https://tanstack.com/start/latest): Routing, SSR, server functions
- [TanStack Router](https://tanstack.com/router/latest): File-based routing, loaders, type safety
- [React](https://react.dev/): Modern React APIs
- [Tailwind CSS v4](https://tailwindcss.com/): Design tokens & utility-first styling
- [Base UI](https://base-ui.com/): Unstyled, accessible React components
- [TanStack Query](https://tanstack.com/query/latest): Server-state syncing & caching
- [nuqs](https://nuqs.dev/): Type-safe URL search param state
- [Zod](https://zod.dev/): Runtime validation and parsing
- [ViraStack AI](https://github.com/virastack/ai): Shared agent rules package (`@virastack/ai`)
