React Project Generator

A CLI tool to scaffold React and React Native projects: generate folder structures, add shadcn/ui components, and add npm library components with AI-generated spec, constraints, tests, and Storybook stories.

Features

• Generate project structure — Choose React or React Native and a folder preset (Atomic Design, Feature-Based, Flat, Layered, Domain-Driven). Creates src/ with folders and .gitkeep files.
• Add shadcn component — Installs a component from shadcn/ui into atoms (no ui folder). Creates test, Storybook stories, spec.md, and constraint.md. Optionally AI-generated (spec, constraint, tests, stories) when OPENAI_API_KEY is set.
• Add library component — Installs any npm package (e.g. react-calendar), creates a wrapper component under atoms, and generates spec, constraint, tests, and stories. AI can generate the wrapper and all docs from the package name and description.
• AI support — Uses OpenAI-compatible API (OpenAI or Groq free tier). Loads .env from project root or package root. Writes ai-generation-errors.md when generation fails.

Installation

Run without installing (recommended)

npx react-project-gen-huzafa

Or with a specific action and argument:

npx react-project-gen-huzafa atom button
npx react-project-gen-huzafa library react-calendar

Install globally

npm install -g react-project-gen-huzafa

Then run from any directory:

react-project-generator

Install as a dev dependency

npm install --save-dev react-project-gen-huzafa

Add a script in package.json:

{
  "scripts": {
    "scaffold": "react-project-generator",
    "add-atom": "react-project-generator atom",
    "add-library": "react-project-generator library"
  }
}

Usage overview

1. Open a terminal in your project root (where you run the CLI).

2. Run:

   npx react-project-gen-huzafa

3. Choose one of:

   • Generate project structure — React/React Native + folder preset.
   • Add shadcn component — Enter component name (e.g. button, alert-dialog).
   • Add library component — Enter npm package name (e.g. react-calendar, @radix-ui/react-dialog).

You can also skip the menu and pass the action and argument:

npx react-project-gen-huzafa atom button
npx react-project-gen-huzafa add-atom card
npx react-project-gen-huzafa library react-calendar
npx react-project-gen-huzafa add-library @radix-ui/react-dialog

1. Generate project structure

Creates a folder structure under src/ with empty directories and .gitkeep files so Git tracks them.

Steps:

1. Run the CLI and choose Generate project structure.
2. Select project type: React or React Native.
3. Select folder structure: Atomic Design, Feature-Based, Flat, Layered, or Domain-Driven.
4. The CLI creates all folders under src/ and prints the list.

Example:

npx react-project-gen-huzafa
# → Generate project structure
# → React
# → Atomic Design

Available structures:

| Structure | Description | |-------------------|-----------------------------------------------------------------------------| | Atomic Design | Atoms → Molecules → Organisms → Templates, plus screens, hooks, utils | | Feature-Based | Feature modules (auth, dashboard, profile) and shared components/hooks/utils | | Flat | Simple: components, screens, hooks, utils, assets | | Layered | Presentation, application, domain, infrastructure | | Domain-Driven| DDD-style: domain, application, infrastructure, presentation |

Example output (Atomic Design):

src/
├── components/
│   ├── atoms/
│   ├── molecules/
│   ├── organisms/
│   └── templates/
├── screens/
├── hooks/
└── utils/

2. Add shadcn component

Installs a component from shadcn/ui and adds test, Storybook stories, spec.md, and constraint.md. Components go under atoms only (no ui folder).

Requirements:

• Run from a project that has components.json (from shadcn init). The CLI temporarily sets the install path to atoms so shadcn creates files under src/components/atoms/ (or components/atoms/).

Steps:

1. Run the CLI and choose Add shadcn component.
2. Enter the component name in kebab-case (e.g. button, alert, alert-dialog, button-group).
3. The CLI runs npx shadcn@latest add <name>, which installs the component (and dependencies like button, separator if needed) into a flat atoms folder.
4. The main component file (e.g. button-group.tsx) is moved into atoms/<ComponentName>/ (e.g. atoms/ButtonGroup/). Dependencies (e.g. button.tsx, separator.tsx) stay in the flat atoms folder.
5. Test, stories, spec.md, and constraint.md are added in the same folder. If AI is enabled (see Environment and AI), these are AI-generated; otherwise templates are used.

Example:

npx react-project-gen-huzafa
# → Add shadcn component
# → button-group

Or directly:

npx react-project-gen-huzafa atom button-group

Resulting structure:

src/components/atoms/
├── button.tsx           ← dependency (stays in flat atoms)
├── separator.tsx       ← dependency
└── ButtonGroup/
    ├── button-group.tsx   ← main component (moved here)
    ├── button-group.test.tsx
    ├── button-group.stories.tsx
    ├── spec.md
    └── constraint.md

Import in your app:

import { ButtonGroup } from "@/components/atoms/ButtonGroup/button-group";

If AI fails (e.g. quota, network), templates are used and ai-generation-errors.md is written in the same folder with the error details and how to fix (e.g. add billing or use Groq).

3. Add library component

Installs an npm package (e.g. react-calendar, @radix-ui/react-dialog) and creates a wrapper component under atoms with spec, constraint, test, and Storybook stories. All of these can be AI-generated when OPENAI_API_KEY is set.

Steps:

1. Run the CLI and choose Add library component.
2. Enter the npm package name (e.g. react-calendar, @radix-ui/react-dialog).
3. The CLI runs npm install <package> in the current directory.
4. It reads package.json from node_modules/<package> (e.g. description) and creates a folder atoms/<ComponentName>/ (e.g. atoms/ReactCalendar/). Component name is derived from the package name (e.g. react-calendar → ReactCalendar).
5. It generates:
   • Wrapper component (.tsx) — thin wrapper that imports and re-exports (or wraps) the library. Uses import * as React from "react" and a namespace import for the library so it works without esModuleInterop.
   • spec.md — Overview, props, usage, file structure, accessibility.
   • constraint.md — Design/usage constraints, do's and don'ts.
   • Test (.test.tsx) and Stories (.stories.tsx) — basic tests and Storybook CSF3 stories.
6. If AI is enabled, the wrapper and all of the above are AI-generated from the package name and its description. If not, template content is used.

Example:

npx react-project-gen-huzafa
# → Add library component
# → react-calendar

Or directly:

npx react-project-gen-huzafa library react-calendar
npx react-project-gen-huzafa add-library @radix-ui/react-dialog

Resulting structure:

src/components/atoms/ReactCalendar/
├── react-calendar.tsx      ← wrapper (AI or template)
├── react-calendar.test.tsx
├── react-calendar.stories.tsx
├── spec.md
└── constraint.md

Import in your app:

import { ReactCalendar } from "@/components/atoms/ReactCalendar/react-calendar";

Note: The generated wrapper uses import * as React from "react" and a namespace import for the library so it works in projects that do not have esModuleInterop enabled. The CLI also strips any leading "typescript" or "tsx" line from AI output so it is not written into the file.

Environment and AI

The CLI can use AI to generate spec, constraint, tests, and stories (and for library, the wrapper too). It uses an OpenAI-compatible API: OpenAI or Groq (free tier).

Where .env is loaded

The CLI loads .env from two places (in order):

1. Package root — the folder where the CLI package lives (e.g. if you run npm start from the generator repo, it loads .env from that repo).
2. Project root (cwd) — the folder where you run the command (e.g. your React app root). This overrides the package root.

So:

• If you run from your React app: put .env in your React app root.
• If you run from the generator repo (e.g. npm start): put .env in the generator repo root.

Variables

| Variable | Required | Description | |--------------------|----------|-------------| | OPENAI_API_KEY | Yes (for AI) | API key. For OpenAI: API keys. For Groq (free): Groq keys. | | OPENAI_BASE_URL | No | API base URL. Default: https://api.openai.com/v1. For Groq: https://api.groq.com/openai/v1. | | OPENAI_MODEL | No | Model name. Default: gpt-4o-mini. For Groq: e.g. llama-3.3-70b-versatile. |

Example: OpenAI

Create .env in your project root (or package root):

OPENAI_API_KEY=sk-your-openai-key-here
# OPENAI_BASE_URL=https://api.openai.com/v1
# OPENAI_MODEL=gpt-4o-mini

Example: Groq (free tier)

If OpenAI quota is exceeded (429), you can use Groq:

OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_API_KEY=gsk_your-groq-key-here
OPENAI_MODEL=llama-3.3-70b-versatile

Get a key at Groq Console.

When AI is used

• Shadcn component: If OPENAI_API_KEY is set, the CLI sends the component source code to the API and generates spec, constraint, test file, and stories file. Without a key, template content is used.
• Library component: If OPENAI_API_KEY is set, the CLI sends the package name and description to the API and generates the wrapper, spec, constraint, test, and stories. Without a key, template content is used.

When AI fails

If the API returns an error (e.g. 429 quota, 401 invalid key, network error), the CLI:

1. Falls back to template content for the missing files.
2. Writes ai-generation-errors.md in the component folder with the error messages and a short "How to fix" (e.g. add billing, use Groq, check key).

File structure summary

| Action | Where files go | Main files | |---------------------|------------------------------------------|------------| | Project structure | src/ (with preset subfolders) | Folders + .gitkeep | | Shadcn component | src/components/atoms/<Name>/ or components/atoms/<Name>/ | <name>.tsx, <name>.test.tsx, <name>.stories.tsx, spec.md, constraint.md | | Library component | Same as above | Same + wrapper .tsx |

Shadcn dependencies (e.g. button.tsx, separator.tsx) stay in the flat atoms folder; only the component you added gets its own subfolder (e.g. ButtonGroup/).

Troubleshooting

"Permission denied: react-project-generator"

Run with npx so you don’t need a global install:

npx react-project-generator

If you use a global install, ensure the binary is executable (e.g. chmod +x $(which react-project-generator)).

"OPENAI_API_KEY not set" / AI not generating

1. Create .env in the folder where you run the CLI (project root or generator package root).
2. Add OPENAI_API_KEY=sk-... (OpenAI) or use Groq (see Environment and AI).
3. Run the CLI again. You should see e.g. "Loaded .env from project root" and "Generating ... with AI...".

429 insufficient_quota (OpenAI)

Your OpenAI account has no quota left. You can:

1. Add billing: OpenAI Billing.
2. Use Groq (free): In .env set OPENAI_BASE_URL=https://api.groq.com/openai/v1, OPENAI_API_KEY=gsk_..., OPENAI_MODEL=llama-3.3-70b-versatile. Get a key at Groq Console.

401 invalid API key

The key in .env is wrong or revoked. Create a new key (OpenAI or Groq) and update OPENAI_API_KEY in .env.

"UI directory not found" / "Atoms directory not found"

• Shadcn: Ensure components.json exists in the project root (from npx shadcn@latest init). The CLI looks for the component file in src/components/atoms/ or components/atoms/ after shadcn runs.
• Library: Ensure npm install <package> completed (check node_modules/<package>). The CLI then creates src/components/atoms/<Name>/ or components/atoms/<Name>/.

Generated code: "Cannot find name 'typescript'" or "can only be default-imported using esModuleInterop"

• The CLI now instructs AI to not output a "typescript" or "tsx" line at the start of files, and to use import * as React from "react". Fallback templates also use import * as React and namespace imports for libraries.
• If you still see this in an old generated file, remove any first line that is only "typescript" or "tsx", and change import React from "react" to import * as React from "react".

Requirements

• Node.js 18 or later
• npm or yarn
• For shadcn component: a project with components.json (shadcn init)
• For AI: OPENAI_API_KEY in .env (OpenAI or Groq)

Development

git clone <repository-url>
cd generate-folder
npm install

# Build
npm run build

# Run CLI locally
npm start

# Run tests (build + smoke test)
npm test

License

ISC

Author

Huzafa