Quick Start

This guide walks you through creating your first project with React Kickstart.

Interactive Mode (Recommended)

The easiest way to get started is with the interactive prompts. Just run:

npx @gavbarosee/react-kickstart my-app

You'll be asked a series of questions to configure your project:

• Framework: Vite or Next.js?
• Language: TypeScript or JavaScript?
• Styling: Tailwind CSS, styled-components, or plain CSS?
• Routing:
  • For Vite: React Router or none?
  • For Next.js: App Router or Pages Router?
• State management: Redux Toolkit, Zustand, or none?
• API layer: Axios, React Query, fetch, or none?
• Testing: Vitest, Jest, or none?
• Deployment: Vercel, Netlify, or manual setup?
• Package manager: npm or yarn (auto-detected based on your system)
• Git: Initialize a Git repository?
• Linting: Set up ESLint and Prettier?
• Editor: Open in Cursor or VS Code? (Auto-detects which editors you have installed)

Once you've made your choices, the project generates, dependencies install, and (unless you skip it) your editor opens and the dev server starts automatically.

Run Your Project

If the dev server didn't start automatically, or you stopped it:

cd my-app
npm run dev

Your app will be running at:

• Vite: http://localhost:5173
• Next.js: http://localhost:3000

Non-Interactive Mode

You can skip the prompts by using flags to configure everything upfront. Perfect for scripts, CI/CD, or when you know exactly what you want.

npx @gavbarosee/react-kickstart my-app \
  --yes \
  --framework vite \
  --typescript \
  --styling tailwind \
  --routing react-router \
  --state redux \
  --api axios-react-query \
  --testing vitest

Project structure

my-app/
├── src/
│   ├── components/
│   ├── pages/
│   ├── store/              # if state selected
│   ├── api/                # if API selected
│   └── __tests__/          # if testing selected
├── public/
├── package.json
├── vite.config.ts          # or next.config.js
└── tsconfig.json           # if TypeScript selected

Available scripts

What Happens Under the Hood

When you run React Kickstart, here's what happens:

1. Project Generation — Files and folders are created based on your configuration. Everything from entry points to config files to example components.

2. Dependency Installation — npm (or yarn) installs all the packages you need. This takes a minute or two depending on your connection.

3. Git Initialization — A Git repository is initialized with a sensible .gitignore. You can skip this with --no-git.

4. Dev Server — The development server starts automatically so you can see your app immediately. Use --no-autostart to skip this.

5. Summary — You'll see a summary with next steps, useful commands, and links to documentation.

Tips & Troubleshooting

Port already in use? If port 5173 (Vite) or 3000 (Next.js) is taken, the dev server will usually suggest an alternative. You can also manually specify a port in the generated config files.

Dependencies taking forever? The first install is always slower. Subsequent runs are much faster thanks to package manager caching.

Want to regenerate? Not happy with your choices? Just delete the folder and run the command again. Or use --yes with flags to skip prompts entirely.

Need help? Check the generated README.md in your project for guidance specific to your stack choices.

What's Next?

Now that you have a running project:

• Explore the code — Check out the generated files and see how everything is wired together
• Read the README — Your project's README has stack-specific guidance
• Check the CLI Reference — Learn all available flags and options
• Start building — The scaffolding is done. Now make it yours!