Contributing

We'd love your help making React Kickstart better! That said, React Kickstart is a fairly delicate project: it generates real, working applications across multiple frameworks, each with their own conventions and nuances. A small change in one area can have unexpected ripple effects across different configurations.

Before diving into code, please open an issue or feature request on GitHub (opens in a new tab) first. This gives us a chance to discuss the approach, identify potential conflicts, and make sure the contribution aligns with the project's direction. It saves everyone time and ensures your effort has the best chance of being merged.

Quick tip: If you're fixing a typo or updating docs, feel free to submit a PR directly. For anything that touches code generation, testing, or new features, let's chat in an issue first.

Getting Started

Clone Locally

git clone https://github.com/gavbarosee/react-kickstart.git
cd react-kickstart

Install

npm install

Link & Test

Link the CLI globally so you can use it like a real user:

npm link

Now generate a test project and run it:

# Generate a test app
react-kickstart my-test-app 
 
# Test the generated app
cd my-test-app
npm run dev

You can also run tests and linting on the CLI:

# Back in react-kickstart repo
npm test
npm run lint

Make Changes

Create a branch using proper naming conventions:

# For new features
git checkout -b feature/add-solid-js-support
 
# For bug fixes
git checkout -b bug/fix-redux-import
 
# For documentation
git checkout -b docs/update-cli-reference
 
# For improvements/refactoring
git checkout -b refactor/simplify-generator-logic

Make your changes and commit frequently. A light test suite runs automatically before each commit to catch issues early.

Submit PR

Push your branch and open a PR. A PR template will guide you through providing all the necessary information:

Description of changes
Type of change (bug fix, new feature, docs, etc.)
Testing performed
Breaking changes (if any)

Note that the full matrix validation test suite runs before push to ensure your changes work across all configurations.

For emergencies, you can skip the pre-push validation:

SKIP_PREPUSH=1 git push

Use this sparingly—the pre-push tests are there to catch issues before they reach CI.

Review & Merge

Your PR will need approval from a maintainer before it can be merged. Once approved:

All CI tests run automatically (unit tests, linting, full QA matrix)
After successful CI, the PR can be merged
A release is automatically created and published to npm

This automated release process means your contribution goes live immediately after merge. That's why we're careful about what gets approved!

Project Structure

Understanding where things live will help you navigate the codebase and know where to make changes.

react-kickstart/
├── .github/              # GitHub Actions workflows (CI/CD, releases)
├── .husky/               # Git hooks (pre-commit, pre-push)
├── bin/                  # CLI entry point (react-kickstart.js)
├── src/
│   ├── index.js          # Main orchestrator - starts here
│   ├── prompts/          # Interactive CLI prompts and steps
│   │   ├── steps/        # Individual prompt steps (framework, styling, etc.)
│   │   └── prompt-flow.js
│   ├── generators/       # Framework-specific generators
│   │   ├── base-generator.js
│   │   └── frameworks/   # Vite and Next.js generators
│   ├── builders/         # Configuration and package.json builders
│   │   ├── configuration-builder.js
│   │   ├── package-json-builder.js
│   │   └── dependency-resolver.js
│   ├── features/         # Feature modules (styling, state, API, testing, etc.)
│   │   ├── api-clients/
│   │   ├── routing/
│   │   ├── state-management/
│   │   ├── styling/
│   │   ├── testing/
│   │   └── linting/
│   ├── templates/        # Content generation for generated projects
│   │   ├── engines/      # Template rendering logic
│   │   ├── frameworks/   # Framework-specific templates
│   │   └── features/     # Feature-specific templates
│   ├── errors/           # Error handling and cleanup
│   └── utils/            # Utilities (filesystem, logging, git, etc.)
│       ├── core/         # Core utilities (fs, validation, formatting)
│       ├── process/      # Process utilities (package managers, git, editor)
│       └── ui/           # UI utilities (logging, summaries, output)
├── qa-automation/        # Matrix testing framework
│   ├── test-runner.js
│   ├── test-matrix-generator.js
│   ├── configs/          # Test configurations
│   └── reports/          # Generated test reports
├── __tests__/            # Unit tests
├── docs/                 # Internal documentation
└── scripts/              # Build and utility scripts

Key areas for contributors:

Adding a framework? → src/generators/frameworks/ + src/prompts/steps/framework-step.js
Adding a feature option? → src/features/ + corresponding prompt step
Changing dependencies? → src/builders/dependency-resolver.js + src/builders/dependencies.js
Modifying generated code? → src/templates/
Updating tests? → __tests__/ for unit tests, qa-automation/ for integration tests

Testing

Unit Tests

npm test
npm run test:coverage

QA Automation

Automated testing validates generated projects build, run, and pass tests.

# Critical tests (fast)
npm run qa:critical
 
# Full test suite
npm run qa:standard
 
# Test specific framework
node qa-automation/test-runner.js --framework vite

Test configs in qa-automation/configs/. Add tests when adding features.

Git Hooks

The project uses automated Git hooks to maintain code quality:

Pre-commit: A light test suite runs automatically before each commit, including:

Linting checks (ESLint)
Code formatting (Prettier)
Quick unit tests

Pre-push: The full matrix validation test suite runs before pushing to catch configuration issues across all supported framework combinations. This is more thorough but takes longer.

If you need to push urgently (fixing a critical issue or emergency deployment), you can skip the pre-push validation:

SKIP_PREPUSH=1 git push

⚠️

Use SKIP_PREPUSH=1 sparingly. The pre-push tests catch real issues before they reach CI. If you skip them, double-check that CI passes before merging.

Releases

Releases are automated via GitHub Actions:

Version bump: Update package.json version
Tag: Create git tag (e.g., v1.2.3)
Push: Tag triggers CI/CD pipeline
Publish: Automated publish to npm
Nightly builds: Automated tests run nightly on main branch

See .github/workflows/ for CI/CD configuration.

Guidelines

Code Quality:

Pass ESLint and Prettier checks
Add tests for new features
Update docs as needed
Use conventional commits

Pull Requests:

Discuss major changes in an issue first
Keep PRs focused and reasonably sized
Ensure CI passes

Getting Help

Need assistance or have questions?

Issues (opens in a new tab) — Bug reports and specific problems
Discussions (opens in a new tab) — Questions, feature ideas, and general chat
Pull Requests (opens in a new tab) — Ask questions in PR comments during reviews

We try to respond to issues within a couple of days and review PRs within a week, though sometimes it might take longer depending on complexity.