React Vite Boilerplate

Everything you need to start with your next Vite + React web app! Delighful developer experience with batteries included.

Demo

react-vite-boilerplate.webm

Technical Blog 1

Technical Blog 2

Table of Contents

• Overview
• Requirements
• Getting Started
• Scaffold via npx
• Scripts
• Open Source Setup
• Publishing and Releases
• Release System Diagram
• Versioning Guide
• Owner Release Checklist
• Complete Owner Example
• Important Note
• Testing
• Deployment
• DevTools
• Installed Packages

Overview

Built with type safety, scalability, and developer experience in mind. A batteries included Vite + React template.

A more detailed list of the included packages can be found in the Installed Packages section.

Requirements

• NodeJS 24.x (see .nvmrc)
• npm

Getting Started

Getting started is a simple as cloning the repository

git clone https://github.com/singhAmandeep007/react-vite-boilerplate.git

Changing into the new directory

cd react-vite-boilerplate

Removing the .git folder (and any additional files, folders or dependencies you may not need)

rm -rf .git

Installing dependencies

npm install

And running the setup script (initializes git repository and husky)

npm run prepare

Congrats! You're ready to starting working on that new project!

Note: This project comes with two git hooks added by husky. A pre-commit hook that runs lint-staged and a commit-msg hook that runs commitlint + devmoji. You can simply run npm run commit after staging your changes to create automagical ✨ emojified conventional commit message.

If you wish to remove any hooks, simply delete the corresponding file in the .husky directory.

If you want to ignore husky hooks for a specific commit, you can use the --no-verify flag. Eg. git commit -m "your message" --no-verify

Scaffold via npx

This template can be scaffolded using the published CLI package:

npx @singhamandeep/crvb@latest my-app

Then run:

cd my-app
npm install
npm run dev

Scripts

App

npm run dev
npm run build
npm run preview
npm run preview:local:msw

Storybook

npm run storybook
npm run storybook:build
npm run test:storybook

Tests

npm test
npm run test:unit
npm run test:unit:coverage
npm run test:unit:watch
npm run test:unit:ui
npm run test:e2e
npm run test:e2e:headless

Code Quality

npm run lint
npm run format
npm run tsc:check
npm run tsc:watch

Setup

npm run init:msw
npm run prepare

Open Source Setup

The repository includes standard open-source project files:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• Issue templates
• Pull request template

Publishing and Releases

This repository uses a two-phase release model powered by Changesets:

Phase	What happens	Who does it
1. Feature PR	Code changes + .changeset/*.md entry	Developer
2. Release PR	Automated version bump, changelog, npm publish	CI (GitHub Actions)

Key files

File	Purpose
.changeset/config.json	Versioning and changelog strategy
.github/workflows/release.yml	CI: lint → typecheck → test → version → publish
packages/crvb/package.json	Publish target (@singhamandeep/crvb)

One-time Setup

1. Create an npm account and login locally: npm login.
2. Add NPM_TOKEN as a GitHub Actions secret in repository settings.
3. Add GH_RELEASE_TOKEN (a PAT with contents:write and pull-requests:write scope) as a GitHub Actions secret for the changesets bot to create Release PRs.
4. Ensure your default branch is main.

Release Flow

Feature Branch ──► PR to main ──► Merge
                                     │
                          ┌──────────▼────────────┐
                          │   release.yml runs    │
                          │  ┌──────────────────┐ │
                          │  │ npm ci           │ │
                          │  │ lint             │ │
                          │  │ typecheck        │ │
                          │  │ unit tests       │ │
                          │  │ npm auth verify  │ │
                          │  └────────┬─────────┘ │
                          │           │           │
                          │  changesets/action    │
                          │  detects .changeset/* │
                          └──────────┬────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │        Release PR created       │
                    │  • version bump in package.json │
                    │  • CHANGELOG.md updated         │
                    └────────────────┬────────────────┘
                                     │
                              Merge Release PR
                                     │
                          ┌──────────▼──────────┐
                          │  changeset publish  │
                          │  → npm registry     │
                          │  → GitHub Release   │
                          └─────────────────────┘

Release System Diagram

flowchart LR
  subgraph DEV[Developer Local]
    A1[Code changes]
    A2["Quality checks\nlint · typecheck · test"]
    A3["npm run changeset\ncreates .changeset/*.md"]
    A4[Push feature branch]
  end

  subgraph CI[GitHub Actions - release.yml]
    B0["CI quality gate\nlint · typecheck · test:unit"]
    B1[Feature PR merged to main]
    B2["changesets/action\nversion command"]
    B3["Release PR created\nversion bump + changelog"]
    B4[Release PR merged]
    B5["changesets/action\npublish command"]
  end

  subgraph REG[NPM Registry]
    C1["@singhamandeep/crvb published"]
    C2["npx @singhamandeep/crvb@latest\nresolves to new version"]
  end

  A1 --> A2 --> A3 --> A4 --> B1 --> B0 --> B2 --> B3 --> B4 --> B5 --> C1 --> C2

Loading

Versioning Guide

For package @singhamandeep/crvb, use semantic versioning:

Bump	Version	When to use	Example
patch	x.y.Z	Bug fixes, internal changes, no CLI behavior change	Fix degit cache issue
minor	x.Y.z	New features, backward compatible	Add new prompt option
major	X.y.z	Breaking changes requiring user action	Rename CLI command

When to Use major

• CLI command or flag is renamed/removed.
• Scaffold output structure changes in a breaking way.
• Minimum Node.js version requirement increases.
• Default behavior changes (e.g., default package manager switch).

Owner Release Checklist

1. Implement your changes in a feature branch.
2. Run local quality checks:

npm run lint
npm run tsc:check
npm run test:unit
npm run test:storybook

3. Create a changeset:

npm run changeset
# Select @singhamandeep/crvb → choose patch/minor/major → write summary

4. Commit and push:

git add .
npm run commit
git push origin feat/your-feature

5. Open and merge PR to main.
6. Wait for Release PR to be created by the workflow.
7. Review the Release PR:
   • ✅ Version bump is correct
   • ✅ Changelog text is clear
   • ✅ No unexpected file changes
8. Merge Release PR → publishes to npm.
9. Verify:

# Check version
npm view @singhamandeep/crvb version

# Test scaffolding
npx @singhamandeep/crvb@latest my-test-app
cd my-test-app && npm run dev

Complete Example

Scenario: Add a --skip-install flag to skip dependency installation (minor version bump).

# 1. Branch
git checkout main && git pull origin main
git checkout -b feat/skip-install-flag

# 2. Make changes to packages/crvb/bin/create.js
#    Add --skip-install flag handling

# 3. Quality checks
npm run lint
npm run tsc:check
npm run test:unit

# 4. Changeset
npm run changeset
# → Select @singhamandeep/crvb
# → Choose: minor
# → Summary: "Add --skip-install flag to bypass dependency installation"

# 5. Commit
git add .
npm run commit
# → feat: add --skip-install flag to CLI

# 6. Push and open PR
git push origin feat/skip-install-flag
# Open PR on GitHub → merge after review

# 7. Release PR appears automatically
# Review: version 1.1.0 → 1.2.0, changelog looks good
# Merge Release PR

# 8. Verify
npm view @singhamandeep/crvb version  # → 1.2.0
npx @singhamandeep/crvb@latest test-app --skip-install

Important Note

1. This boilerplate project includes a recommended folder structure for organizing your application code in logical and opinionated way.

The folder structure is as follows:

├── .storybook
├── cypress
│   ├── downloads
│   ├── fixtures
│   ├── specs
│   ├── support
|   └── tsconfig.json
├── env
├── public
├── src
│   ├── __mocks__
│   ├── app
│   ├── api
│   ├── assets
│   ├── components
│   │   ├── forms
│   │   ├── hooks
│   │   ├── layout
│   │   ├── ui
│   │   └── developmentTools.tsx
│   ├── config
│   ├── mocker
│   ├── modules
│   │   └── i18n
│   ├── pages
│   │   ├── app
│   │   ├── home
│   │   └── auth
│   ├── routes
│   ├── store
│   │   └── auth
│   ├── tests
│   ├── types
│   ├── utils
│   └── index.css
│   └── main.tsx
├── index.html
├── .editorconfig
├── eslint.config.js
├── prettier.config.js
├── cypress.config.js
├── tailwind.config.js
├── .gitignore
├── tsconfig.json
├── vite.config.ts
└── package.json

2. There are README files which contain simple descriptions about how the different directories in the accompanying folder structure may be used. As an example check out the recommended component organizational structure.

Storybook-specific configuration and usage are documented in .storybook/README.md.

Testing

Unit Testing

Unit testing is handled by React Testing Library and Vitest.

If you'd like to run Unit tests, execute the following command:

npm run test:unit

# or with coverage
npm run test:unit:coverage

# or in watch mode
npm run test:unit:watch

# or in ui mode
npm run test:unit:ui

Testing types is also supported with vitest and this application is set up to run tests for types using it. By default all tests inside *.test-d.ts files are considered type tests.

Storybook Testing

Component stories can be tested with Vitest through Storybook.

npm run test:storybook

Accessibility checks are enabled for story tests and configured to fail on violations.

End-to-End (E2E) Testing

End-to-End (E2E) Testing is conducted by Cypress.

If you'd like to run E2E tests, execute the following command:

npm run test:e2e

# or in headless mode
npm run test:e2e:headless

Continuous Integration

Github Actions has been set up to run tests on every push to the repository. The configuration can be found in the .github/workflows directory.

Workflow for cypress tests is located in .github/workflows/cypress.yml. This workflow integrates cypress-mochawesome-reporter to automatically generate standalone HTML reports of your test runs, complete with embedded screenshots and videos, and attaches them as Artifacts to the GitHub Actions run for you to download publicly.

Devtools

This project includes a set of Devtools. Some are additional package dependencies whereas others come built-in to the packages themselves.

Devtool dependencies:

• @tanstack/react-query-devtools - Dedicated dev tools to help visualize the inner workings of React Query
• @tanstack/router-devtools - Dedicated dev tools to help visualize the inner workings of TanStack Router
• @hookform/DevTools - React Hook Form Devtools to help debug forms with validation

A set of utility components are provided in developmentTools.tsx. These wrapper components check whether the application is running in development or production mode and render the component or null respectively. In other words, you can confidently use them during development without having to worry about them showing up for end users in production.

TanStack Query Devtools are ready to go out of the box. The development vs. production rendering mechanism is built into the devtools. If you do wish to render the devtools in production you can freely do so by following the TanStack Query Devtools documentation. The devtools component can be found in App.tsx.

When running the application in development mode you can find the TanStack Query Devtools icon in the bottom left corner of the page sporting the React Query Logo.

TanStack Router Devtools, however, utilizes its respective utility component in this project. The initial setup has been taken care of but if you wish to modify or remove the component, have a look in src/routes__root.tsx.

The TanStack Router Devtools icon can be found in the bottom left corner of the page denoted by "Tanstack Router" logo.

React Hook Form DevTools icon can be recognized in the top left corner of the page by the pink React Hook Form clipboard logo. A prop must be passed from a specific hook to enable it. In this case, it is the control prop from the useForm() hook. Use of React Hook Form DevTools requires the component be added to each unique form. More information can be found in the React Hook Form DevTools documentation.

To reiterate, if you wish to restrict the Devtools to development builds use the provided components found at src/components/utils/developmentTools instead of the built-in components from their respective modules.

Installed Packages

Base

• TypeScript - Typed superset of JavaScript
• Vite - Feature rich and highly optimized frontend tooling with TypeScript support out of the box
• React - A modern front-end JavaScript library for building user interfaces based on components

Routing

• TanStack Router - Fully typesafe, modern and scalable routing solution for react applications.

Linting & Formatting

• ESLint - Static code analysis to help find problems within a codebase
  • typescript-eslint
  • eslint-plugin-react
  • eslint-plugin-react-hooks
  • eslint-plugin-react-refresh
  • eslint-plugin-cypress
  • eslint-plugin-storybook
  • eslint-plugin-testing-library
• Prettier - Code formatter
  • prettier-plugin-organize-imports
  • prettier-plugin-tailwindcss

State Management

• TanStack React Query - Powerful asynchronous state management, server state caching, and data fetching library
• Zustand - A small, fast and scaleable bearbones state-management solution using flux principles.
  • Provides a built-in devtools middleware

Utils

• Radash - A powerful utility library with functions having strong types and zero dependencies
• date-fns - Modern JavaScript date utility library
• ky - A tiny and elegant HTTP client which provides cool benefits over plain fetch

Internationalization

• i18next-browser-languageDetector
• i18next
• react-i18next - A powerful internationalization framework for React/React Native based on i18next

UI

• Tailwind CSS - A utility-first CSS framework packed with classes to build any web design imaginable
• Shadcn UI - A set of beautiful and accessible React components
• Lucide
• Storybook - A frontend workshop for building UI components and pages in isolation

Forms

• React Hook Form - Performant, flexible and extensible forms with easy-to-use validation
• Zod - TypeScript-first schema validation with static type inference

Testing

• Vitest - Vitest is a fast testing framework for modern web applications with first-class support for TypeScript and Vite
• React Testing Library - A very light-weight, best practice first, solution for testing React components
• Cypress - A powerful end-to-end testing framework that simplifies and accelerates web application testing
• MSW - Industry standard API mocking for JavaScript designed to work across any frameworks, tools, and environments

Development Tools

• TanStack Query Devtools
• TanStack Router Devtools
• React Hook Form Devtools

Git

• Husky - Automatically lint your commit messages, code, and run tests upon committing or pushing.
• Commitizen - Conventional commit messages CLI
• lint-staged - Run linters against staged git files and don't let 💩 slip into your code base!
• Devmoji - A CLI tool to help you write conventional commit messages with emojis

Other

• Faker - Generate massive amounts of fake (but realistic) data for testing and development