Overview
Opinionated ecosystem for building Vite-based React SPAs with a consistent architecture, library stack, and UI system (src/ui).
Tech stack
| Layer | Choice |
|---|---|
| Bundler | Vite |
| Language | TypeScript |
| Styling | Tailwind CSS v4, class-variance-authority (cva + cx from the same package) |
| Routing | TanStack Router (file-based, src/routes) |
| Server state | TanStack Query |
| Client global state | Zustand |
| HTTP | Axios |
| Dates | date-fns (src/libs/date-utils/) |
| Presentational UI | shadcn/ui-style primitives in src/ui/ |
Setup
| Item | Required | When | How |
|---|---|---|---|
| Standing rule | required | Scaffold new app | Add - `<target_path>` follows building-react-web-application; load it before changing code there. to root AGENTS.md (create when missing) and to root CLAUDE.md when it exists without importing AGENTS.md; skip a file that has it |
Agent workflow
Follow this skill for Vite + React SPA work. Resolve every required Setup row, then match Entry points and Task types; open every linked reference from matched rows and from the component decision tree before coding.
Entry points
Use the first row that matches; combine rows when the task spans types (e.g. new route + form).
| Entry | When | Go to |
|---|---|---|
| Component | Building, moving, or recategorizing any component | creating-component |
| Structure | Folder roles, dependency flow, or where a module belongs | managing-project-structure |
| Task bundle | API, forms, styling, bootstrap, testing, fonts, routing-only, navigation | Task types table |
| Lookup | You know the doc name or need a single reference | Reference index |
Task types
Match every row that applies. Open every link in the Docs column from each matching row.
Reference index
| Reference | Entry | Layer | Purpose |
|---|---|---|---|
| creating-api | API | HTTP modules under src/api/ |
|
| creating-component | Component | Component | Decision tree and shared rules for any component work |
| creating-e2e-testing | Testing | Playwright E2E tests | |
| creating-feature | Feature | Feature module folders and barrels | |
| creating-feature-component | Component | Domain UI blocks in features | |
| creating-form-component | Form | Form fields and form shells | |
| creating-navigation-component | Route | Reusable layout navigation (shells, sidebars, headers) | |
| creating-route-component | Route | Flat files in src/routes/ — filenames map to URLs |
|
| creating-screen-component | Feature | Route-facing *Page in src/features/<feature>/components/ |
|
| creating-ui-component | Component | Shared primitives in src/ui/ |
|
| discovering-registry-components | Component | Registry component lookup by intent and labels | |
| managing-api-error | API | API error handling patterns | |
| managing-date | Date | date-fns parsing, formatting, and src/libs/date-utils/ |
|
| managing-environment | Setup | Feature env.ts and env vars |
|
| managing-form-error | Form | Form validation and error display | |
| managing-linting | Setup | ESLint and Prettier setup | |
| managing-package-installs | Setup | Package manager detection and install scripts | |
| managing-project-structure | Structure | Architecture | Folder layout and dependency flow |
| managing-state | State | TanStack Query hooks and Zustand stores | |
| managing-stepper-form | Form | Multi-step form UI | |
| managing-stepper-hook | Form | Multi-step form state hook | |
| managing-styling | Styling | Styling conventions and token preference | |
| managing-wrapper-components | Component | Wrapper and composition patterns | |
| overriding-classname | Styling | className override rules |
|
| scaffolding-application | Setup | Vite react-ts scaffold |
|
| setting-up-axios | API | Axios client setup | |
| setting-up-theming | Styling | Design tokens and theme CSS | |
| setting-up-tailwind-theme | Styling | Tailwind theme configuration |