React TypeScript Starter

Advanced reusable React TypeScript configuration with modern tooling and best practices.

Features

• ⚡ Vite - Lightning fast HMR and builds
• 🔷 TypeScript - Full type safety
• ⚛ React 18 - Latest React with concurrent features
• 🛣️ React Router v6 - Client-side routing
• 🎨 BiomeJS - Fast linting and formatting
• 🧪 Vitest - Unit testing with coverage
• 🎭 Playwright - Cross-browser E2E testing
• 📱 PWA - Progressive Web App with service worker
• 🎯 Stylelint - CSS linting with BEM naming
• 🗺️ Sitemap - Auto-generated sitemap.xml
• 🤖 robots.txt - Auto-generated robots.txt
• 🚀 Bun - Fast JavaScript runtime & package manager

Getting Started

Prerequisites

• Node.js 18+ (recommended: 20+) OR Bun 1.0+
• npm, yarn, pnpm, or bun

Installation

# Clone or copy this project
cd react-typescript-starter

# Install dependencies (using bun - recommended)
bun install

# Or using npm
npm install

Development

# Start development server (using bun)
bun run dev

# Or using npm
npm run dev

# The app will be available at http://localhost:3000

Available Scripts

Script	Description
bun run dev	Start development server
bun run dev:bun	Start dev server with Bun runtime
bun run build	Build for production
bun run build:bun	Build with Bun runtime
bun run preview	Preview production build
bun run test	Run unit tests (Vitest)
bun run test:bun	Run tests with Bun test runner
bun run test:coverage	Run tests with coverage
bun run test:e2e	Run E2E tests (Playwright)
bun run lint	Lint with BiomeJS
bun run lint:fix	Lint and fix issues
bun run format	Format code
bun run lint:css	Lint CSS
bun run typecheck	Run TypeScript check
bun run validate	Run typecheck, lint, and CSS lint
bun run validate:full	Full validation including unit tests (use Node)
bun run test:run	Run unit tests once (requires Node — see below)
bun run deps:check	Check for unused or missing dependencies

Project Structure

├── src/
│   ├── components/       # Reusable UI components
│   ├── pages/            # Page components
│   ├── styles/           # Global styles
│   ├── test/             # Test setup
│   ├── App.tsx           # Main app component
│   └── main.tsx          # Entry point
├── e2e/                  # Playwright E2E tests
├── scripts/              # Build scripts
├── public/               # Static assets
├── bunfig.toml           # Bun configuration
├── vite.config.ts        # Vite configuration
├── vitest.config.ts      # Vitest configuration
├── playwright.config.ts  # Playwright configuration
├── tsconfig.json         # TypeScript configuration
├── biome.json            # BiomeJS linting/formatting
└── stylelint.config.js   # CSS linting rules

Configuration Files

File	Purpose
bunfig.toml	Bun runtime configuration
vite.config.ts	Vite configuration with PWA
vitest.config.ts	Vitest test configuration
playwright.config.ts	Playwright E2E configuration
tsconfig.json	TypeScript configuration
biome.json	BiomeJS linting/formatting
stylelint.config.js	CSS linting rules

Testing

Unit Tests (Vitest)

Vitest runs under Node.js (via npm exec) because Bun's runtime is not compatible with Vitest worker pools.

# Run all tests once
npm run test:run

# Run tests in watch mode
npm run test

# Run tests with coverage
npm run test:coverage

E2E Tests (Playwright)

# Install Playwright browsers
npx playwright install

# Run E2E tests
npm run test:e2e

# Run with UI mode
npm run test:e2e:ui

# Debug tests
npm run test:e2e:debug

Bun Integration

This project is fully compatible with Bun as an alternative to Node.js.

Why Bun?

• 25x faster package installs compared to npm
• Native TypeScript support without compilation
• Built-in test runner compatible with Jest
• Faster script execution with native performance

Bun Commands

# Install dependencies
bun install

# Add a package
bun add <package>

# Remove a package
bun remove <package>

# Run any script
bun run <script>

# Execute TypeScript directly
bun run src/main.tsx

bunfig.toml

Configuration file for Bun behavior:

[install]
linker = "hoisted"

[test]
timeout = 10000
coverage = false

[serve]
port = 3000

PWA Support

The app is configured as a Progressive Web App with:

• Service worker for offline support
• Web app manifest for installation
• Automatic updates

CSS Architecture

Uses CSS with BEM naming convention:

/* Block */
.card { }

/* Element */
.card__title { }
.card__content { }

/* Modifier */
.card--featured { }

Code Quality

• BiomeJS for linting and formatting
• Stylelint for CSS linting
• TypeScript for type safety
• Vitest for unit testing
• Playwright for E2E testing

Deployment

Build

npm run build

The build output will be in the dist/ directory.

Environment Variables

Copy .env.example to .env and adjust values for your project:

cp .env.example .env

VITE_APP_TITLE=My App
SITE_URL=https://your-domain.com

• VITE_APP_TITLE — exposed to the client via src/utils/env.ts
• SITE_URL — used at build time for sitemap and robots.txt generation

License

MIT