Documentation

Complete guide to using React Vite Boilerplate CLI tool for creating modern React applications.

Installation

React Vite Boilerplate is available as an npm package. You can use it directly with npx or install it globally.

Using npx (Recommended)

npx @sibilsoren/react-vite-boilerplate my-app

Global Installation

npm install -g @sibilsoren/react-vite-boilerplate
react-vite-boilerplate my-app

Quick Start

Get up and running with a new React project in seconds:

# Create a new project
npx @sibilsoren/react-vite-boilerplate my-app

# Navigate to the project directory
cd my-app

# Start the development server
npm run dev

🎉 That's it!

Your React application will be running at http://localhost:5173 with hot module replacement, TypeScript support, and all the modern tooling you need.

CLI Reference

Basic Usage

react-vite-boilerplate [options] <project-name>

Options

-y, --yes

Skip interactive prompts and use defaults

--pm <manager>

Specify package manager (npm, yarn, pnpm, bun)

--skip-install

Skip package installation

--skip-git

Skip git repository initialization

--verbose

Enable verbose output

--dry-run

Show what would be created without actually creating it

--template <name>

Use a specific template variant

Examples

Create project with yarn

npx @sibilsoren/react-vite-boilerplate my-app --pm yarn

Skip installation and git init

npx @sibilsoren/react-vite-boilerplate my-app --skip-install --skip-git

Preview without creating

npx @sibilsoren/react-vite-boilerplate my-app --dry-run

Features

React Vite Boilerplate comes pre-configured with modern tools and best practices for React development.

React 18 + TypeScript

  • • Latest React 18 with concurrent features
  • • Full TypeScript support with strict mode enabled
  • • React DOM with modern rendering
  • • Pre-configured TypeScript compiler options

Vite Development

  • • Lightning-fast development server with HMR
  • • Optimized production builds with code splitting
  • • Native ES modules support
  • • Built-in TypeScript support

TanStack Router

  • • Type-safe file-based routing
  • • Automatic code splitting by route
  • • Built-in data loading and caching
  • • Search params and state management

Example Route Structure:

src/routes/
├── __root.tsx # Root layout
├── index.tsx # Home page (/)
└── about.tsx # About page (/about)

Shadcn/UI Components

  • • Pre-installed with Button and Card components ready to use
  • • Automated Setup with all required dependencies included
  • • Built on Radix UI for accessibility
  • • Fully customizable with Tailwind CSS
  • • Easy to add more components as needed

Using Pre-installed Components:

import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"

export function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Get Started</Button>
      </CardContent>
    </Card>
  )
}

Adding More Components:

npx shadcn@latest add dialog

Tailwind CSS

  • • Utility-first CSS framework
  • • Configured with custom design tokens
  • • PostCSS integration for processing
  • • Responsive design utilities

SEO Setup

  • • React Helmet Async for dynamic meta tags
  • • Pre-configured HTML meta structure
  • • Environment variable management
  • • SEO-friendly routing setup

Template Structure

Project Structure

my-app/
├── public/ # Static assets
├── src/
│ ├── components/
│ │ └── ui/ # Shadcn/UI components (Button, Card)
│ │ ├── button.tsx
│ │ └── card.tsx
│ ├── hooks/ # Custom React hooks
│ ├── lib/
│ │ └── utils.ts # Utility functions with cn() helper
│ ├── pages/ # Page components
│ ├── routes/ # TanStack Router routes
│ │ ├── __root.tsx
│ │ ├── index.tsx
│ │ └── about.tsx
│ ├── styles/
│ │ └── globals.css # Global styles
│ ├── utils/ # General utilities
│ └── main.tsx # App entry point
├── components.json # Shadcn/UI config
├── index.html # HTML template
├── package.json # Dependencies
├── postcss.config.js # PostCSS config
├── tailwind.config.js # Tailwind config
├── tsconfig.json # TypeScript config
├── tsconfig.node.json # Node TypeScript config
└── vite.config.ts # Vite configuration

Key Configuration Files

vite.config.ts

Vite configuration with TanStack Router plugin

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { TanStackRouterVite } from '@tanstack/router-vite-plugin'

export default defineConfig({
  plugins: [react(), TanStackRouterVite()],
})

tailwind.config.js

Tailwind CSS configuration with design tokens

module.exports = {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        // Custom color system
      }
    }
  }
}

Configuration

Package Managers

React Vite Boilerplate supports multiple package managers with automatic detection:

  • • npm - Default Node.js package manager
  • • yarn - Fast, reliable, and secure dependency management
  • • pnpm - Fast, disk space efficient package manager
  • • bun - Ultra-fast JavaScript runtime and package manager

The CLI automatically detects your preferred package manager based on existing lock files or falls back to npm.

Customization

Environment Variables

The template includes environment variable setup with TypeScript support:

# .env
VITE_APP_TITLE=My React App
VITE_API_BASE_URL=https://api.example.com

Adding Dependencies

Add new dependencies using your preferred package manager:

# With npm
npm install lodash
npm install -D @types/lodash

# With yarn
yarn add lodash
yarn add -D @types/lodash

Troubleshooting

Common Issues

Package installation fails

If package installation fails, try the following:

  • • Check your internet connection
  • • Clear npm cache: npm cache clean --force
  • • Try a different package manager: --pm yarn
  • • Use --skip-install and install manually

TypeScript errors

If you encounter TypeScript errors:

  • • Ensure all dependencies are installed
  • • Restart your TypeScript server in VS Code
  • • Check for missing type definitions
  • • Verify your tsconfig.json configuration

Git initialization fails

If git initialization fails:

  • • Ensure git is installed and configured
  • • Set git user.name and user.email
  • • Use --skip-git to skip git initialization
  • • Initialize git manually after project creation

Error Codes

VALIDATION

Project name or directory validation failed

FILESYSTEM

File system operation failed

PACKAGE_MANAGER

Package manager operation failed

TEMPLATE

Template copying or processing failed

NETWORK

Network connectivity issue

Contributing

We welcome contributions to React Vite Boilerplate! Here's how you can help improve the project.

Development Setup

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

# Install dependencies
npm install

# Run tests
npm test

# Test the CLI locally
node bin/cli.js test-project --verbose

How to Contribute

  • • Fork the repository and create a feature branch
  • • Make your changes and add tests if applicable
  • • Ensure all tests pass: npm test
  • • Run linting: npm run lint
  • • Submit a pull request with a clear description

Areas for Contribution

  • • Adding new template variants
  • • Improving error handling and messages
  • • Adding more CLI options and features
  • • Enhancing documentation and examples
  • • Bug fixes and performance improvements

💡 Have Ideas?

Open an issue on GitHub to discuss new features or improvements. We'd love to hear your suggestions!