React TypeScript Starter

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

CLI (npm / Bun)

Scaffold a new project anywhere:

# npm
npx typescript-quick create my-app --install

# Bun
bunx typescript-quick create my-app --install --pm bun

Commands:

| Command | Description | |---------|-------------| | typescript-quick create <dir> | Copy the starter template into <dir> | | typescript-quick create <dir> --install | Scaffold and install dependencies | | typescript-quick create <dir> --pm bun | Use Bun for install | | typescript-quick --version | Print CLI version |

Publish the CLI (maintainers):

NPM_TOKEN=your_token bun run publish:cli

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