create-vibe-react

A CLI that scaffolds production-ready React 19 + TypeScript + Vite projects with opinionated conventions, strict linting, and a full modern tech stack — ready to build on from day one.

npx create-vibe-react init

What You Get

A fully configured project with:

• React 19 with the React Compiler (auto-memoization, no manual memo/useMemo/useCallback)
• TypeScript in strict mode with path aliases (@/)
• Vite with code splitting, SVGR, and source maps
• Tailwind CSS v4 + shadcn/ui (41 components pre-installed)
• Zustand for client state, React Query for server state
• React Hook Form + Zod for form handling and validation
• React Router DOM v7 for routing
• i18next for internationalization
• dayjs wrapped in datetime-utils for safe date handling
• Sentry integration with error boundaries and console overrides
• ESLint flat config with strict rules + Prettier
• Husky + lint-staged pre-commit hooks (typecheck + lint)
• Vitest + React Testing Library for unit tests
• Playwright for E2E tests
• 20 AI rule files (.cursor/rules/) + CLAUDE.md for AI-assisted development

Quick Start

Install globally (optional)

npm install -g create-vibe-react

Create a project

create-vibe-react init

You'll be prompted for:

1. Project name — lowercase alphanumeric with hyphens (e.g. my-app)
2. API type — how you'll talk to your backend:
   • REST OpenAPI spec — generates hooks from OpenAPI/Swagger via Orval
   • GraphQL schema — generates typed hooks via GraphQL Code Generator
   • Buf protobuf — generates Connect-RPC hooks via Buf
3. Sentry DSN (optional) — for error tracking

The CLI then runs 19 automated steps — from create vite to the initial git commit — and you're ready to cd my-app && yarn dev.

Generated Project Structure

my-app/
├── src/
│   ├── components/        # Shared React components
│   │   └── ui/            # shadcn/ui components (auto-generated, not linted)
│   ├── e2e/               # Playwright E2E tests
│   ├── generated/         # Auto-generated API hooks (DO NOT EDIT)
│   ├── hooks/             # Custom hooks (use-*.ts)
│   ├── layouts/           # Layout wrappers
│   ├── lib/               # Utilities (cn() for Tailwind)
│   ├── modules/
│   │   └── sentry/        # Sentry wrapper — import from here, not @sentry/react
│   ├── pages/             # Route-based page components
│   ├── providers/         # QueryProvider, ThemeProvider, SentryProvider
│   ├── routes/            # Router configuration
│   ├── shared/
│   │   ├── constants/     # App-wide constants
│   │   ├── i18n/          # i18next config + locale JSON files
│   │   ├── stores/        # Zustand stores (*.store.ts)
│   │   ├── types/         # Shared TypeScript types
│   │   └── utils/         # datetime-utils, errors, console-overrides
│   └── test/              # Vitest setup and helpers
├── api/                   # OpenAPI spec or GraphQL schema (depends on API type)
├── proto/                 # Protobuf definitions (Buf API type only)
├── .cursor/rules/         # 20 AI rule files for Cursor IDE
├── CLAUDE.md              # AI conventions for Claude Code
├── eslint.config.js       # Strict ESLint flat config
├── vitest.config.ts       # Unit test configuration
├── playwright.config.ts   # E2E test configuration
└── ...

Available Scripts (Generated Project)

Development

| Command | Description | |---|---| | yarn dev | Start Vite dev server | | yarn build | TypeScript build + Vite production build | | yarn preview | Preview production build locally |

Code Quality

| Command | Description | |---|---| | yarn lint | Run ESLint | | yarn lint:fix | Auto-fix ESLint violations | | yarn format | Format all files with Prettier | | yarn format:check | Check formatting without writing | | yarn typecheck | TypeScript type-check (no emit) |

Testing

| Command | Description | |---|---| | yarn test | Run Vitest once | | yarn test:watch | Vitest in watch mode | | yarn test:coverage | Generate coverage report | | yarn e2e | Run Playwright E2E tests | | yarn e2e:ui | Playwright interactive UI mode | | yarn e2e:debug | Playwright debug mode |

API Code Generation

| Command | Description | |---|---| | yarn generate:api | Generate typed hooks from your API spec | | yarn generate:clean | Remove all generated API code |

Enforced Conventions

The generated ESLint config enforces strict rules to keep the codebase consistent and maintainable:

| Rule | Rationale | |---|---| | No useEffect | Use React Query for data fetching, event handlers for side effects | | No createContext / useContext | Use Zustand for state management | | No useMemo / useCallback / React.memo | React Compiler handles memoization automatically | | No direct @sentry/react imports | Import from @/modules/sentry wrapper | | No direct dayjs imports | Import from @/shared/utils/datetime-utils | | No new Date() | Use now(), parseDate() from datetime-utils | | No console.log / console.error | Use Sentry for error tracking; only console.warn and console.debug allowed | | No any type | Use unknown and narrow with type guards | | No hardcoded strings in JSX | Use i18n translations (useTranslation()) | | Type imports required | import type { Foo } enforced by ESLint | | Semicolons required | Consistent style across the project |

TypeScript Naming Conventions

• TUser, TApiResponse — prefix types with T
• IConfig, IProps — prefix interfaces with I
• EUserRole, EStatus — prefix enums with E
• use-example.ts — kebab-case hook files with use prefix
• example.store.ts — store files with .store.ts suffix

API Types in Detail

REST (Orval)

Generates React Query hooks from an OpenAPI/Swagger specification.

• Spec location: api/openapi.yaml
• Config: orval.config.ts
• Output: src/generated/api/

GraphQL (Code Generator)

Generates typed React Query hooks from a GraphQL schema.

• Schema location: api/schema.graphql
• Config: codegen.ts
• Output: src/generated/graphql/

Protobuf (Buf + Connect-RPC)

Generates Connect-RPC hooks from protobuf definitions.

• Proto location: proto/example/v1/example.proto
• Config: buf.yaml + buf.gen.yaml
• Output: src/generated/proto/

Pre-commit Hooks

Every commit automatically runs:

1. tsc --noEmit — full TypeScript type-check
2. lint-staged — ESLint + Prettier on staged files only

This ensures no type errors or lint violations make it into the repository.

AI-Assisted Development

The scaffolded project includes configuration for AI coding assistants:

• .cursor/rules/ — 20 rule files covering React Query usage, Zustand patterns, testing, i18n, error handling, Sentry, design system usage, and more
• CLAUDE.md — project conventions and tech stack summary for Claude Code

These files help AI assistants follow the same strict conventions enforced by ESLint.

For a full breakdown of every AI rule file, see AI_RULES.md. For CLI development conventions, see CLAUDE.md.

Requirements

• Node.js >= 18
• yarn (used for dependency installation)

Development (CLI itself)

git clone <repo-url>
cd react-cli
yarn install
yarn build        # Compile TypeScript
yarn dev          # Watch mode
node dist/index.js init   # Test locally

License

ISC