create-react-forge

Production-ready React scaffolding CLI with first-class testing, flexible runtimes (Vite/Next.js), and a composable template system inspired by bulletproof-react.

Requirements

• Node.js >= 20.9.0

Quick start

Create a new project (interactive):

npx create-react-forge@latest

Or install globally:

npm install -g create-react-forge
create-react-forge

What it does

When you run create-react-forge, it will:

• Ask a few questions (runtime, language, styling, testing, etc.)
• Generate a new project directory (the directory must not already exist)
• Optionally initialize a git repository
• Print the "next steps" commands

Note: it does not automatically install dependencies — you'll run your package manager install after generation.

Interactive prompts

The CLI is prompt-driven. You'll choose:

• Project name (lowercase letters/numbers/hyphens)
• Project directory
• Runtime: Vite or Next.js
• Language: TypeScript or JavaScript
• Styling: Tailwind, Styled Components, CSS Modules, or Plain CSS (Vite offers all 4; Next.js auto-selects Tailwind)
• State: none, Zustand, Jotai, or Redux Toolkit
• Testing: full (unit+component+E2E), unit+component only, or none
• Unit runner: Vitest or Jest (if testing enabled)
• E2E runner: Playwright or Cypress (if full testing)
• Data fetching: include TanStack Query
• Package manager: npm / yarn / pnpm
• Git init: yes/no

What you get

A production-ready React project with a scalable, feature-based structure:

my-app/
├── src/
│   ├── app/              # App setup (providers, router)
│   ├── components/       # Shared UI components
│   │   ├── ui/           # Base UI primitives
│   │   └── errors/       # Error boundaries & fallbacks
│   ├── features/         # Feature-based modules
│   ├── hooks/            # Custom hooks
│   ├── lib/              # Utilities, API client
│   ├── stores/           # State management (if selected)
│   ├── styles/           # Global styles
│   ├── testing/          # Test utilities, mocks (if selected)
│   └── types/            # Shared types (TypeScript projects)
├── tests/                # E2E tests (if selected)
├── README.md             # Auto-generated project README
├── ARCHITECTURE.md       # Auto-generated architecture docs
└── [config files]

For JavaScript projects, TypeScript-only files are omitted automatically.

Configuration options

| Category | Choices | | ------------------- | ------------------------------------------------------------------------------------------- | | Runtime | vite, nextjs | | Language | typescript, javascript | | Styling | tailwind, styled-components, css-modules, css (Vite: all 4, Next.js: tailwind only) | | State | none, zustand, jotai, redux | | Testing | full, unit-component, none | | Unit runner | vitest, jest | | E2E runner | playwright, cypress | | Data fetching | TanStack Query on/off | | Package manager | npm, yarn, pnpm | | Git | init on/off |

Dependency versions

The CLI uses pinned, tested versions for all dependencies:

| Package | Version | | -------------- | -------- | | React | ^19.0.0 | | Vite | ^6.0.7 | | Next.js | ^16.1.6 | | Tailwind CSS | ^4.0.0 | | TanStack Query | ^5.62.10 | | Vitest | ^2.1.8 | | Playwright | ^1.49.1 | | TypeScript | ^5.7.2 |

Automated dependency updates

This repo now uses Renovate to auto-update dependencies (including template manifests under src/templates/overlays/**/manifest.json, src/dependencies/resolver.ts, and the dependency versions table in this README) on a weekly schedule.

One-time setup

1. Create a fine-grained GitHub PAT with repository contents, pull requests, and issues write access.
2. Add it as repository secret: RENOVATE_TOKEN.
3. Enable repository auto-merge in GitHub settings.
4. Protect master and require CI checks before merge.

Workflow file: .github/workflows/renovate.yml
Config file: renovate.json

Behavior:

• All dependency updates (major, minor, patch) auto-merge after checks pass.

Screenshot

Next steps (after generation)

cd <your-project>
npm install
npm run dev

Advanced: API exports

This package exposes advanced entrypoints for tooling integration:

Config schema (Zod)

import { ProjectConfigSchema, DEFAULT_CONFIG } from 'create-react-forge/config';

const parsed = ProjectConfigSchema.parse(DEFAULT_CONFIG);

Template registry

import { TemplateRegistry } from 'create-react-forge/templates';

const registry = new TemplateRegistry();
const templates = registry.loadTemplatesForConfig({
  runtime: 'vite',
  styling: { solution: 'styled-components' },
  stateManagement: 'zustand',
  testing: {
    enabled: true,
    unit: { runner: 'vitest' },
    e2e: { enabled: true, runner: 'playwright' },
  },
  dataFetching: { enabled: true },
});

Troubleshooting

• "Directory already exists": pick a new project directory (or delete the existing folder).
• Node version issues: ensure node -v is 20.9.0+.
• Install step: dependencies are not installed automatically — run your package manager install in the generated folder.

Architecture & development

See ARCHITECTURE.md for internal design details.

npm install
npm run dev       # Run CLI in development
npm run test      # Run tests
npm run build     # Build to dist/

License

MIT