Building a Production Ready React Vite TypeScript Boilerplate

Overview

As developers, we often find ourselves setting up the same tools and configurations when starting new projects. To address this challenge, I've created a fully type-safe React + Vite boilerplate/starter that serves as a solid foundation for production-ready web applications which scales well.

This template emerged from a need to standardize new projects at work, focusing on developer experience, code quality, and scalability. Let me walk you through what makes this boilerplate special and how you can use it for your next project.

Key Features

🚀 Lightning-fast development with Vite
💪 Full TypeScript support
🗂️ Well organized project structure
🔒 Includes JWT authentication implementation
📡 Modern data fetching with Tanstack React Query
🗃️ State management using Zustand
🛣️ Type-safe and File based routing with Tanstack Router
🌐 Internationalization support (i18n)
📝 Form handling with React Hook Form + Zod
🎨 UI components with Tailwind CSS + shadcn/ui
📚 Component documentation using Storybook
✅ Comprehensive testing setup with Vitest + Cypress + MSW

Requirement

• Node.js 20+
• npm
• git

Getting Started

Installation

# Clone the repository
git clone https://github.com/singhAmandeep007/react-vite-boilerplate.git

# cd into folder
cd react-vite-boilerplate

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

# Install dependencies
npm install

# Run the setup script (initializes git repository and husky)
npm run prepare

# Start development server, yeah that's all
npm run dev

Project Structure

├── .storybook
├── cypress
│   ├── downloads
│   ├── fixtures
│   ├── specs
│   ├── support
|   └── tsconfig.json
├── env
├── public
├── src
│   ├── __mocks__
│   ├── app
│   │   ├── auth.ts
│   │   ├── App.ts
│   │   └── router.ts
│   ├── assets
│   ├── api
│   │   ├── auth
│   │   ├── posts
│   │   ├── user
│   │   └── apiService.ts
│   ├── 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

Key folders and files with purpose

Root Directory

• .storybook/: Contains configuration files for Storybook, a popular tool for building UI components and testing them in isolation.
• cypress/: Holds end-to-end testing configurations and files.
  • downloads/: For storing temporary downloads during tests.
  • fixtures/: Mock data for testing.
  • specs/: Test cases for Cypress.
  • support/: Custom commands and reusable configurations.
  • tsconfig.json: TypeScript configuration specific to Cypress.
• env/: Environment-specific files (e.g., .env.development, .env.production).
• public/: Publicly accessible assets, such as images or static files.
• index.html: Entry point for the application.
• Configuration files for linting, formatting, and build tools:
  • .editorconfig, eslint.config.js, prettier.config.js
  • tailwind.config.js: Tailwind CSS configuration.
  • vite.config.ts: Vite configuration.
  • tsconfig.json: TypeScript compiler configuration.

src Directory
The src folder contains the core of the application:

• __mocks__/: Mock files for testing purposes.
• app/: Application-level configurations, such as providers (e.g., for React Query, Router, etc.).
• api/: Directory is organized into folders of related API endpoints.
• assets/: Stores static resources that are part of application.
• components/:
  • forms/: Reusable form components like input fields or buttons.
  • hooks/: Custom React hooks.
  • layout/: Components related to the app's layout (headers, footers).
  • ui/: Reusable UI components (buttons, cards).
  • developmentTools.tsx: Tools or utilities for local development, such as react query devtools.
• config/: Configuration files, such as API base URLs or environment settings.
• mocker/: For mocking API responses or other utilities during development.
• modules/:
  • i18n/: Internationalization configurations and translation files.
• pages/: Top-level pages, often aligned with routes.
  • App/: Pages related to the main application (dasboard, settings).
  • Home/: Homepage or landing page.
  • Auth/: Authentication-related pages (login, signup).
• routes/: File based Route configuration for the app, using Tanstack router.
• store/: Global state management, organized by domain.
  • auth/: State management logic for authentication.
• tests/: Utility functions and wrappers for unit testing.
• types/: Shared TypeScript types and interfaces.
• utils/: Reusable utility functions and helpers.
• index.css: Global CSS or Tailwind imports.
• main.tsx: Application entry point, initializing React and rendering the app.

Authentication Implementation

The boilerplate includes a complete JWT authentication setup demonstrating best practices:

Data Flow

• API requests using ky for modern HTTP client capabilities. Ky allows modification the request lifecycle using hooks.
• Request/response handling with React Query for caching and synchronization
• State management through Zustand for auth status and user data
• Protected routes implementation with Tanstack Router

Testing

The boilerplate comes with a comprehensive testing setup:

• Unit Tests: Vitest + React Testing Library
• E2E Tests: Cypress
• API Mocking: MSW (Mock Service Worker)

Unit Testing

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.

End-to-End (E2E) Testing

npm run test:e2e

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

Development Tools

• Dev tools
  • @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

• Code Quality

  • ESLint for code linting
  • Prettier for code formatting
  • husky for git hooks
  • commitizen + devmoji for standardized commit messages

• Pre-commit Checks

  • The boilerplate automatically runs the following checks before each commit:
  • Linting
  • Type checking
  • Format checking

Deployment

The project includes GitHub Actions workflows for:

• Continuous Integration

  • Running e2e tests
  • Code quality checks

• Continuous Deployment

  • Automatic deployment to production environments

Conclusion

This boilerplate aims to provide a solid foundation for your React projects while maintaining flexibility. It incorporates modern tools and best practices without being overly opinionated, allowing you to adapt it to your specific needs.

What's Next?

• Clone the repository
• Check out the demo implementation
• Customize it for your project
• Provide feedback or contribute

Remember one design doesn't fit all, so feel free to customize it according to your needs.

Your feedback and contributions are always welcome! Feel free to open issues or submit pull requests on GitHub.

Resources

• GitHub Repository
• Live Demo
• Documentation

Feedback and questions are always welcome and I appreciate anyone willing to checkout this project.

Goodluck shipping you next project.