# ViraStack Start — TanStack Start Edition (i18n)

> Premium TanStack Start + React 19 + Tailwind CSS 4 boilerplate with **Paraglide JS** i18n (`en`, `tr`). Feature-sliced architecture, agent-ready DX. Auth, database/ORM, and testing are intentionally omitted.

Built on TanStack Router file-based routing with SSR via TanStack Start. Messages live under `messages/`; Paraglide generates `src/paraglide`. UI: **Base UI** + Tailwind CSS 4. State triad: TanStack Query, Zustand, `nuqs`. Forms: React Hook Form + Zod. **ViraStack AI** ships on scaffold.

- Tech stack: TanStack Start, TanStack Router, React 19, Tailwind CSS 4, TypeScript strict, Node.js `>=20.9`
- i18n: `@inlang/paraglide-js` — `project.inlang/settings.json` language tags `en` (source) and `tr`; compiled output in `src/paraglide`
- 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`)
- Env: Zod schema in `src/env.ts` (`VITE_*` public vars)
- Tooling: ESLint 9, Prettier 3, Husky, Knip, Commitlint, Changesets, Vite 8
- ViraStack AI: `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, `docs/*`
- Not included by default: Auth, DB/ORM, test runner, CSP

## Docs
- [Repository (GitHub)](https://github.com/virastack/start): CLI and templates
- [README](https://github.com/virastack/start/tree/main/templates-i18n/tanstack): This edition
- [i18n docs](https://virastack.com/start/docs/i18n): Locale and message 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
- [Architecture guide](https://github.com/virastack/ai/blob/main/templates/core/docs/architecture-guide.md): Placement rules
- [Paraglide JS](https://inlang.com/m/gerre34r/library-inlang-paraglideJs): i18n library docs

## Key Files & Entry Points
- [`src/routes/__root.tsx`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/src/routes/__root.tsx): Root route, document shell, providers, SEO head
- [`src/routes/index.tsx`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/src/routes/index.tsx): Home → `<LandingPage />`
- [`project.inlang/settings.json`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/project.inlang/settings.json): Language tags and Paraglide settings
- [`messages/en.json`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/messages/en.json): English message source
- [`messages/tr.json`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/messages/tr.json): Turkish message source
- [`src/paraglide/`](https://github.com/virastack/start/tree/main/templates-i18n/tanstack/src/paraglide): Generated runtime (do not hand-edit)
- [`src/start.ts`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/src/start.ts): Global request middleware
- [`src/router.tsx`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/src/router.tsx): Router factory + Query SSR
- [`src/env.ts`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/src/env.ts): Zod env (`VITE_*`)
- [`src/config/site.config.ts`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/src/config/site.config.ts): Site config
- [`src/lib/api.ts`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/src/lib/api.ts): Fetch wrapper + `ApiError`
- [`src/providers/Providers.tsx`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/src/providers/Providers.tsx): Theme, Nuqs, Toaster
- [`vite.config.ts`](https://github.com/virastack/start/blob/main/templates-i18n/tanstack/vite.config.ts): Vite + TanStack Start + Paraglide + Tailwind

## Landing Feature (demo — delete when building)
Canonical tree under `src/features/landing/`. Use Paraglide message functions for UI copy.

Quick start: delete `src/features/landing`, replace home route, keep shared layout if useful.

## Architecture for agents
- Feature-Sliced: `src/features/[feature]/` — no cross-feature imports
- Prefer short aliases; promote shared code only via Rule of Three
- Edit `messages/*.json` (or inlang sources), not generated `src/paraglide` output
- Brand name `ViraStack` stays untranslated
- Search for `FIXME:` after scaffold

## ViraStack AI
- Refresh: `npx @virastack/ai init --force`
- Package: [`@virastack/ai`](https://github.com/virastack/ai)

## External References
- [TanStack Start](https://tanstack.com/start)
- [TanStack Query](https://tanstack.com/query/latest)
- [Paraglide JS](https://inlang.com/m/gerre34r/library-inlang-paraglideJs)
- [nuqs](https://nuqs.dev/)
- [Zod](https://zod.dev/)
