Use when scaffolding a new React project, adding React to an existing project, or generating a feature-complete application structure. Prevents the common mistake of inconsistent project setup with missing TypeScript, linting, or test configuration. Covers Vite config, TypeScript setup, component architecture, routing, state management, testing infrastructure, folder structure. Keywords: scaffold, Vite, project structure, TypeScript config, folder layout, new React app, create project, project template, getting started, bootstrap React..
Use when scaffolding a new React project, adding React to an existing project, or generating a feature-complete application structure. Prevents the common mistake of inconsistent project setup with missing TypeScript, linting, or test configuration. Covers Vite config, TypeScript setup, component architecture, routing, state management, testing infrastructure, folder structure. Keywords: scaffold, Vite, project structure, TypeScript config, folder layout, new React app, create project, project template, getting started, bootstrap React..
license
MIT
compatibility
Designed for Claude Code. Requires React 18.x or 19.x with TypeScript and Vite.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
react-agents-project-scaffolder
Quick Reference
Project Size Classification
Size
Routes
Components
State Complexity
Team
Small
1-5
< 20
Local state only
1-2 devs
Medium
5-20
20-80
Shared + server state
3-8 devs
Large
20+
80+
Complex orchestration
8+ devs
Generated Stack Summary
Layer
Small
Medium
Large
Build
Vite + @vitejs/plugin-react
Vite + @vitejs/plugin-react
Vite + @vitejs/plugin-react
Language
TypeScript (strict)
TypeScript (strict)
TypeScript (strict)
Routing
React Router v6
React Router v6
React Router v6
Client State
useState/useReducer
Zustand
Zustand
Server State
fetch + useEffect
TanStack Query
TanStack Query
Styling
CSS Modules
CSS Modules
CSS Modules
Testing
Vitest + RTL
Vitest + RTL
Vitest + RTL + Playwright
Linting
ESLint flat config
ESLint flat config
ESLint flat config
Critical Warnings
NEVER scaffold with Create React App -- it is deprecated and unmaintained. ALWAYS use Vite with @vitejs/plugin-react.
NEVER use default tsconfig.json -- ALWAYS enable strict: true, noUncheckedIndexedAccess: true, and configure path aliases.
NEVER install both @types/react and React 19 -- React 19 ships built-in TypeScript types. ALWAYS check the React version before adding @types/react.
NEVER mix CSS-in-JS runtime libraries (styled-components, emotion) with React Server Components -- they require client-side JavaScript. ALWAYS use CSS Modules or Tailwind for RSC-compatible projects.
NEVER place test setup files inside src/ -- ALWAYS place setup.ts at the project root or in a dedicated test/ directory.
Project Size Decision Tree
START: What is the project scope?
│
├─ Prototype / landing page / single feature?
│ └─ → SMALL project scaffold
│
├─ Multi-page app with auth, forms, API integration?
│ └─ → MEDIUM project scaffold
│
├─ Enterprise app with complex state, many teams, SSR needs?
│ └─ → LARGE project scaffold
│
└─ Unsure?
└─ → Default to MEDIUM (scales both directions)
SSR Decision
Does the project need SSR or static generation?
│
├─ YES → Use a React framework (Next.js, Remix, TanStack Start)
│ This skill generates the SPA scaffold only.
│ Adapt the patterns below to your framework's conventions.
│
└─ NO → Continue with Vite SPA scaffold below.
ALWAYS install:
├── react@^18.3.0
├── react-dom@^18.3.0
├── @types/react@^18.3.0 (required -- React 18 has no built-in types)
├── @types/react-dom@^18.3.0
├── typescript@^5.5.0
├── vite@^6.0.0
├── @vitejs/plugin-react@^4.0.0
├── eslint@^9.0.0
├── prettier@^3.0.0
└── vitest@^2.0.0
If MEDIUM or LARGE, also install:
├── react-router-dom@^6.28.0
├── @tanstack/react-query@^5.0.0
├── @testing-library/react@^16.0.0
├── @testing-library/jest-dom@^6.0.0
├── @testing-library/user-event@^14.0.0
└── jsdom@^25.0.0
If MEDIUM or LARGE with shared client state:
└── zustand@^5.0.0
If LARGE, also install:
├── @playwright/test@^1.48.0
└── msw@^2.0.0
React 19.x Dependencies
ALWAYS install:
├── react@^19.0.0
├── react-dom@^19.0.0
├── (NO @types/react -- React 19 ships built-in types)
├── (NO @types/react-dom -- React 19 ships built-in types)
├── typescript@^5.5.0
├── vite@^6.0.0
├── @vitejs/plugin-react@^4.0.0
├── eslint@^9.0.0
├── prettier@^3.0.0
└── vitest@^2.0.0
Remaining dependencies are the same as React 18.x above.
ALWAYS check the target React version before generating package.json. The @types/react difference between React 18 and 19 causes type conflicts if installed incorrectly.
Styling Decision
Default: CSS Modules
│
├─ Team already uses Tailwind? → Install tailwindcss@^4.0.0
│ └─ ALWAYS use Tailwind v4 (CSS-first config, no tailwind.config.js)
│
├─ Need design tokens / theming? → CSS Modules + CSS custom properties in tokens.css
│
└─ Building a component library? → CSS Modules (maximum portability)
Scaffolding Checklist
When generating a React project, ALWAYS complete every item:
Create index.html with <div id="root"></div> and <script type="module" src="/src/main.tsx"></script>
Create vite.config.ts with path aliases and @vitejs/plugin-react
Create tsconfig.json with strict mode and path aliases
Create tsconfig.node.json for build tool files
Create src/main.tsx with createRoot (React 18) or createRoot (React 19)
Create src/app/App.tsx (medium/large) or src/components/App.tsx (small)
Create routing setup if medium/large (src/app/router.tsx)
Create providers wrapper if medium/large (src/app/providers.tsx)
Create test/setup.ts with testing-library matchers
Create eslint.config.js with flat config format
Create .prettierrc with consistent formatting rules
Create .gitignore with node_modules, dist, .env, coverage
Create .env.example with VITE_ prefixed variables
Create package.json with all dependencies and scripts
Verify no @types/react if React 19
Reference Links
references/examples.md -- Complete scaffold output for small, medium, and large projects
