React Folder Structure & Conventions
Opinionated setup guide and coding conventions for React + Vite + TypeScript + shadcn/ui projects.
When to Apply
Reference these guidelines when:
- Bootstrapping a new project from scratch
- Creating a new feature inside
components/features/ - Adding a new API domain (TanStack Query + Axios)
- Creating or scoping a Zustand store
- Adding a shadcn/ui component
- Deciding where a file or hook belongs in the project
Rule Categories
| Category | Area | Prefix |
|---|---|---|
| Project Setup | Bootstrapping Vite + Tailwind + shadcn | setup- |
| Folder Structure | Top-level src/ layout | structure- |
| Features | Self-contained feature architecture | feature- |
| API Layer | Axios + TanStack Query conventions | api- |
| State Management | Zustand (global & scoped) | store- |
| Styling | Tailwind v4 + CSS design tokens | style- |
| Naming | File, component & hook naming conventions | naming- |
Quick Reference
Setup
setup-vite— Scaffold Vite + React + TypeScript + Tailwind v4 + path aliasessetup-shadcn— Initialize shadcn/ui and never edit generated ui components
Features
feature-structure— Self-contained feature directory layoutfeature-components— What goes incomponents/vsshared/feature-boundaries— Features may only import each other's root export
API
api-client— Single Axios instance inapi/client.tsapi-endpoints— Centralized endpoint constants, never hardcode URLsapi-query-hooks— Query key factories + TanStack Query hook patternsapi-domain-folder— One folder per domain withuse<Domain>Api.ts+types.ts
State
store-global—src/stores/for app-wide state onlystore-scoped— Context-scopedcreateStore()pattern for feature-local state
Styling
style-tokens— Always use CSS variable tokens, never raw Tailwind color utilitiesstyle-dark-mode— Dark mode via.darkclass +@custom-variant
Full Reference
For detailed explanations and Incorrect/Correct code examples for every rule: AGENTS.md
Individual rule files are in rules/.