Project Structure Walkthrough

A comprehensive, visual guide to understanding React Kickstart's codebase organization, execution flow, and where everything lives.

For New Contributors: Run node bin/react-kickstart.js my-app --yes locally first to see it work, then use this guide to understand the internals.

🎯 TL;DR (Quick Start)

Execution Flow: Prompts collect answers → Framework generator runs → Files/configs are written → Dependencies install → Dev server starts → Summary prints

Key Entry Points:

Start reading: src/index.js → src/prompts/prompt-flow.js → src/generators/frameworks/*-generator.js
Configs/scripts: src/builders/* (configuration/package-json/dependency management)
Files/features: src/features/* and src/templates/* (file generation/content/styling/routing/testing)

When Stuck: Search for the keyword you picked in prompts (e.g., "vite"), then follow the function calls.

🏗️ High-Level Architecture

📁 Directory Structure

react-kickstart/
├── bin/
│   └── react-kickstart.js          # CLI entry point
├── src/
│   ├── index.js                    # Main orchestrator
│   ├── prompts/                    # Interactive prompts
│   ├── generators/                 # Framework generators
│   ├── builders/                   # Configuration builders
│   ├── features/                   # Feature integrations
│   ├── templates/                  # Code generation
│   ├── errors/                     # Error handling
│   └── utils/                      # Utilities
├── qa-automation/                  # Quality assurance
├── package.json                    # CLI metadata & deps
├── eslint.config.js               # Linting rules
└── vitest.config.js               # Test configuration

🔄 Execution Flow Diagram

┌──────────────────────┐      ┌───────────────────────┐      ┌──────────────────────────┐
│      Developer       │  ==> │  bin/react-kickstart  │  ==> │       src/index.js        │
│   (runs the CLI)     │      │     (CLI entry)       │      │ (createApp Orchestrator) │
└─────────┬────────────┘      └───────────┬───────────┘      └──────────────┬───────────┘
          │                                │                                 │
          │                                │                                 ▼
          │                                │                    ┌─────────────────────────┐
          │                                │                    │  prompts/prompt-flow.js │
          │                                │                    │  + steps/* (choices)    │
          │                                │                    └───────────┬────────────┘
          │                                │                                │ answers
          │                                │                                ▼
          │                                │                 ┌───────────────────────────┐
          │                                │                 │ generators/base-generator │
          │                                │                 │ + concrete generators      │
          │                                │                 │   (Vite, Next.js, etc.)   │
          │                                │                 └─────┬───────┬───────┬─────┘
          │                                │                       │       │       │
          │                                │     configs           │       │       │ files/features
          │                                │     (build/test/ts)   │       │       │ (src/public)
          │                                │                       ▼       ▼       ▼
          │                                │               ┌────────────────┐  ┌─────────────────┐
          │                                │               │ src/builders/  │  │ src/features/   │
          │                                │               │ - configuration │  │ - api-clients   │
          │                                │               │ - package-json  │  │ - source-files  │
          │                                │               │ - dep-resolver  │  │ - styling       │
          │                                │               └────────────────┘  │ - routing       │
          │                                │                                   │ - testing/ts    │
          │                                │                                   └─────────┬───────┘
          │                                │                                             │
          │                                │                                 ┌───────────▼───────────┐
          │                                │                                 │    src/templates/     │
          │                                │                                 │ (content generation)  │
          │                                │                                 └──────────────────────┘
          │                                ▼
          │                    ┌─────────────────────────────────────┐
          │                    │ utils/process/package-managers.js   │
          │                    │  → install deps (npm/yarn)          │
          │                    └───────────────────┬─────────────────┘
          │                                        │
          │                                        ▼
          │                          ┌─────────────────────────────────┐
          │                          │ utils/process/start-project.js  │
          │                          │  → run dev server, open browser │
          │                          └─────────────────┬──────────────┘
          │                                            │
          ▼                                            ▼
┌────────────────────────┐                  ┌──────────────────────────────┐
│ utils/ui/completion.js │                  │  qa-automation/ (optional)   │
│ → final summary/tips   │                  │  - test-matrix-generator     │
└────────────────────────┘                  │  - test-runner, reports      │
                                            └──────────────────────────────┘

🧩 Key Components Deep Dive

🎯 Core Orchestration (`src/index.js`)

The main orchestrator that coordinates the entire application flow:

Initialize & Validate

Parse command line arguments
Validate project name and directory
Display welcome screen

Collect User Preferences

Run interactive prompts (or use flags)
Validate and normalize choices
Apply intelligent defaults

Generate Project

Select appropriate framework generator
Execute generation sequence
Handle errors and cleanup

Post-Processing

Install dependencies
Initialize Git repository
Start development server
Display completion summary

💬 Prompt System (`src/prompts/`)

Architecture:

prompt-flow.js - Multi-step prompt orchestration
steps/ - Individual prompt definitions
ui/prompt-renderer.js - Beautiful CLI interface
navigation/step-navigator.js - Forward/backward navigation

Key Features:

Conditional prompts based on previous answers
Intelligent defaults and validation
Beautiful, branded CLI interface
Support for both interactive and non-interactive modes

🏗️ Generator System (`src/generators/`)

Template Method Pattern:

// BaseGenerator defines the sequence
class BaseGenerator {
  async generate(projectPath, projectName, userChoices) {
    await this.createPackageConfiguration()
    await this.createFrameworkConfiguration()
    await this.createProjectFiles()
    await this.createFrameworkSpecificFiles()
  }
}
 
// Concrete generators implement specific steps
class ViteGenerator extends BaseGenerator {
  async createFrameworkConfiguration() {
    // Vite-specific configuration
  }
}

⚙️ Builder System (`src/builders/`)

Configuration Management:

ConfigurationBuilder - Creates framework configs (vite.config.js, next.config.js, tsconfig.json)
PackageJsonBuilder - Generates scripts and manages dependencies
DependencyResolver - Smart dependency placement (dependencies vs devDependencies)

Dependency Management:

// Smart dependency resolution
const deps = DependencyResolver.getAllDependencies(framework, features)
// Result: { dependencies: {...}, devDependencies: {...} }

🎨 Feature System (`src/features/`)

Modular feature integrations that can be mixed and matched:

🌐 API Clients

Axios, Fetch, React Query integration with base setup classes

📁 Project Files

Core file generation (HTML, entry points, App components)

🧭 Routing

React Router setup for Vite, Next.js routing configuration

🎨 Styling

CSS, Tailwind, styled-components with framework-specific setup

🗃️ State Management

Redux Toolkit, Zustand scaffolding with example implementations

🧪 Testing

Vitest, Jest setup with framework-specific configurations

📝 Template System (`src/templates/`)

Content Generation Architecture:

engines/ - Core template engines and rendering infrastructure
frameworks/ - Framework-specific content strategies (Vite, Next.js App/Pages Router)
features/ - Feature-specific templates (Redux counter, Zustand store examples)

🧪 Quality Assurance System

Automated Testing (`qa-automation/`)

React Kickstart includes comprehensive QA automation to validate all combinations:

# Generate exhaustive test matrix
node qa-automation/test-matrix-generator.js
 
# Run different test suites
node qa-automation/test-runner.js critical 10    # Most important combinations
node qa-automation/test-runner.js standard 25   # Common combinations  
node qa-automation/test-runner.js edge 15       # Edge cases

QA Components:

test-matrix-generator.js - Generates all possible combinations
test-runner.js - Executes generation + install + build + validation
feature-validator.js - Verifies structure, dependencies, scripts, build outputs
reports/ - JSON reports for each test run

Coverage: Every framework/feature combination is automatically tested to ensure compatibility and prevent regressions.

🛠️ Common Development Tasks

Adding a New Framework

Create Generator

Implement *-generator.js extending BaseGenerator in src/generators/frameworks/

Register Framework

Add case in src/generators/index.js for generator selection

Add to Prompts

Include in src/prompts/steps/framework-step.js choices

Wire Dependencies

Update src/builders/* for dependencies and scripts

Update QA Matrix

Include in qa-automation/test-matrix-generator.js

Adding a New Feature

Create Feature Module - Add under src/features/
Wire Dependencies - Update src/builders/dependency-resolver.js
Add Templates - Create content in src/templates/*
Add Prompt - Create step in src/prompts/steps/*
Update QA - Include in test matrix

Modifying Build Configuration

Scripts: src/builders/package-json-builder.js → getFrameworkScripts()
Build Directory: src/builders/package-json-builder.js → getBuildDirectory()
Dependencies: src/builders/dependencies.js for version updates

🔍 End-to-End Example: Vite + TypeScript + Tailwind + Redux

1. User runs CLI:

node bin/react-kickstart.js my-app --yes

2. Choices made:

Framework: Vite
Language: TypeScript
Styling: Tailwind CSS
State: Redux Toolkit
Testing: Vitest

3. Result:

Complete Vite project with all features integrated
Dependencies installed
Dev server started at http://localhost:5173

🐛 Debugging Tips

Quick Debug: Add UI_UTILS.log() calls in src/index.js, BaseGenerator.generate(), or any step to trace execution.

Common Debug Scenarios:

Narrow Scope: Hardcode userChoices in src/index.js to bypass prompts
Validate Dependencies: Check generated package.json against DependencyResolver.getAllDependencies() output
Config Issues: Review configuration-builder.js for framework-specific branches
Start Failures: Ensure port is free, try npm run dev manually
Generator Errors: Add try/catch around suspect calls in concrete generators

📚 Next Steps

Explore Further:

Generators → - Framework-specific generation logic
Builders → - Configuration file creation system
Features → - Feature integration modules
Templates → - Code generation templates

Get Involved:

Adding a Framework → - Complete extension guide
Contributing → - How to contribute to React Kickstart
QA System → - Understanding automated testing

Mental Model: Prompts → Generator (by framework) → Config/Files/Features → Install → Start → Summary

How It Works Generators