ReactStarterKit

A modern React starter kit with TypeScript, Vite, SCSS, and comprehensive tooling for building scalable applications.

🧱 One-command scaffold

Use the create CLI to spin up a new app from this starter:

npx @appsbyme/create-reactstarterkit my-app

The CLI will:

1. create the project directory from this template
2. let you choose yarn, npm, or pnpm
3. install dependencies
4. run setup so you can keep/remove optional features
5. reinstall dependencies to regenerate the selected lockfile
6. run verify:fix

⚡ Manual Setup (git clone)

If you're cloning the repo directly instead of using the CLI:

yarn install
yarn setup
yarn install
cp .env.example .env
yarn dev

1. Install dependencies.
2. Run setup and keep only features you want.
3. Reinstall so lockfile and deps match your selected features.
4. Create .env from .env.example.
5. Start the dev server.

🚀 Features

• React 19 with TypeScript
• Vite for fast development and building
• SCSS with clean architecture pattern
• ESLint + Prettier + Stylelint for code quality
• Conventional Commits enforced via commitlint
• React Router for client-side routing (with a screen-reader route announcer)
• Hooks for common UI needs: debounced values, media queries, document title, online status, click-outside, toggles, previous value, API health polling
• UI primitives: ErrorBoundary, Spinner, EmptyState, Field + Input / Textarea, Radix-based Modal, Sonner toasts (@utils re-export)
• TanStack Query for server state (devtools in development) + useHealthCheckQuery alongside fetch-based useHealthCheck
• Zod validation for VITE_* env consumed by the app (invalid values fail fast at startup)
• Path aliases for clean imports
• PostCSS with autoprefixer and automatic px-to-rem conversion (write px, get rem)
• SVG support with vite-plugin-svgr
• Git Hooks (optional) with Husky for automated quality checks
• Docker (optional) support for development and production
• PWA Support (optional) with offline functionality
• Multilanguage (i18n) (optional) with i18next; demo on the components showcase page
• Testing Infrastructure (optional) with Vitest and React Testing Library

📚 Library map and live demo

• Live catalog: run yarn dev and open /components. That page demonstrates buttons, loading and empty states, Field / Input / Textarea, Modal, Sonner toasts, TanStack Query (useHealthCheckQuery), hooks such as useDebouncedValue and useToggle, and a nested ErrorBoundary without crashing the rest of the app.
• Barrel exports: src/components/index.ts and src/hooks/index.ts list what ships with the kit. For large or heavy dependencies, prefer direct imports (for example @components/Button/Button) so tree-shaking stays predictable — see Import conventions under Project structure.
• Bundle analysis: run yarn build:analyze to open a treemap at dist/stats.html. Lucide icons are imported per symbol (tree-shake friendly). Radix UI, Framer Motion, and Sonner add weight when used; remove, replace, or lazy-load if you need a smaller bundle.

🎯 Initial Setup

After cloning this repository, install dependencies and then run the one-off setup script:

yarn install

yarn setup

This interactive script will ask you which optional features you want to keep, then it will collect the project name and description once so the boilerplate metadata can be rewritten for your app:

• PWA Support – Progressive Web App features
• Multilanguage (i18n) – i18next + react-i18next; demo section on the components page
• Testing Infrastructure – Vitest and React Testing Library
• Git Hooks (Husky) – Pre-commit, commit-msg, and pre-push hooks
• Docker – Development and production containerization

The setup script will:

• keep the features you select
• remove the unwanted files, dependencies, and related configuration
• prune empty directories created by the cleanup
• remove all setup scripts once it finishes

After setup completes, run yarn install again so your lockfile and installed dependencies match the finalized project.

Setup scripts and cleanup behavior

• yarn setup is the only supported setup entrypoint.
• The setup flow is intended to be run once per new project.
• After setup completes, the setup scripts remove themselves from the project.

✅ Keep vs Remove Features

Use this as a quick decision guide during yarn setup.

| Feature | Keep it when... | Remove it when... | | -------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- | | PWA | You want installability, offline caching, and app-like behavior. | You are building a standard web app without offline requirements. | | i18n | You need multilingual support now or soon. | Your app is single-language and you want less boilerplate. | | Testing (Vitest + RTL) | You want confidence and maintainable refactors from day one. | You are prototyping quickly and will add tests later. | | Husky + lint-staged + commitlint | You want quality checks enforced for every contributor. | You prefer CI-only checks or minimal local hook friction. | | Docker | Your team uses containerized dev/prod workflows. | You deploy with platform-native tooling and do not need local containers. |

🔧 Environment Variables

Copy the example environment file and configure as needed:

cp .env.example .env

Available Variables

| Variable | Default | Description | | ------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | VITE_APP_TITLE | React Starter Kit | Application title used in the UI | | VITE_UNDER_CONSTRUCTION | false | Shows under-construction screen for all routes | | VITE_API_URL | (optional) | API origin for apiClient; omit or leave empty for same-origin /api/.... When set, must be a valid http(s) URL (validated with Zod). | | API_PROXY_TARGET | (optional) | Dev-only: Vite proxies /api and /ws to this URL (e.g. Django) | | VITE_PWA | false | Enable PWA in development mode | | DOCKER | (auto-set) | Automatically set by docker-compose in containers |

PWA Development Mode

Control PWA behavior in development:

# Disable PWA (default) - no service worker, no install icon
yarn dev

# Enable PWA for testing - full PWA functionality
VITE_PWA=true yarn dev

Default behavior (VITE_PWA=false):

• Service worker not registered
• Manifest link removed from HTML
• No install icon in browser
• Automatic cleanup of existing service workers

Opt-in testing (VITE_PWA=true):

• Full PWA functionality enabled
• Service worker registers and caches assets
• Install icon appears in browser
• Can test offline behavior

Production: PWA always enabled regardless of this setting.

Multilanguage (i18n)

Optional i18n uses i18next and react-i18next with language detection and localStorage persistence. The demo is scoped to a section on the Components page (/components); use the language switcher there to try English and Spanish.

To remove i18n without running the full setup:

yarn setup:i18n

Docker Environment

When running in Docker, these variables are automatically configured:

• DOCKER=true - Disables browser auto-open
• CHOKIDAR_USEPOLLING=true - Enables polling for Vite’s file watcher (Chokidar) when bind mounts are flaky

See .env.example for detailed documentation.

Commands

yarn dev
yarn build
yarn build:analyze   # production build + dist/stats.html bundle treemap (rollup-plugin-visualizer)
yarn preview

yarn api:build
yarn api:start
yarn api:serve

yarn lint
yarn lint:fix
yarn stylelint
yarn stylelint:fix
yarn format
yarn type-check
yarn verify
yarn verify:fix

yarn setup

yarn test          # Run tests in watch mode
yarn test:run      # Run tests once
yarn test:ui       # Open Vitest UI
yarn test:coverage # Generate coverage report

Yarn v1 note: The scripts are named verify / verify:fix on purpose. Running yarn check invokes Yarn’s built-in dependency integrity command, not this project’s quality gate—use yarn verify (or yarn run verify) instead.

🌐 API Quick Example

The shared API client lives in src/api/apiClient.ts. With VITE_API_URL set, relative paths are resolved against that origin; when it is unset, paths stay same-origin (pair with API_PROXY_TARGET in dev). Central paths live in src/configs/apiEndpoints.ts.

import { apiClient } from '@api';
import { API } from '@configs';

type HealthResponse = { status: string };

async function loadHealth() {
    try {
        const data = await apiClient.get<HealthResponse>(API.health);
        return data.status;
    } catch (error) {
        if (error instanceof Error) {
            throw new Error(`Failed to load health: ${error.message}`);
        }
        throw new Error('Failed to load health');
    }
}

useHealthCheck in src/hooks/useHealthCheck.ts wraps polling against API.health.

For more details and patterns, see src/api/README.md.

If you want an optional backend layer, see api/README.md. It can be used for mock responses during development or as a lightweight backend/BFF layer for simple production scenarios.

🪝 Git Hooks

This project optionally supports and uses Husky to enforce code quality through Git hooks:

Pre-commit Hook

Automatically runs before each commit:

• ESLint with auto-fix on .js/.ts/.jsx/.tsx files
• Stylelint with auto-fix on .css/.scss files
• Prettier formatting on all staged files

Commit Message Hook

Enforces Conventional Commits format:

# Valid commit messages
git commit -m "feat: add new feature"
git commit -m "fix: resolve bug in component"
git commit -m "docs: update README"
git commit -m "chore: update dependencies"

# Invalid - will be rejected
git commit -m "Added new feature"  # Missing type
git commit -m "FEAT: something"    # Uppercase type

Valid types: feat, fix, improve, docs, format, refactor, perf, test, chore, ci, build, revert

Pre-push Hook

Runs before pushing to remote:

• Type checking with TypeScript (yarn type-check)
• Unit tests once (yarn test:run)

Production builds are not run on every push (to keep pushes fast); run yarn build locally or in CI when you need a full compile check.

These hooks help maintain code quality and prevent broken code from entering the repository.

Note: You can bypass hooks with --no-verify flag, but this is not recommended.

# Skip hooks (not recommended)
git commit -m "message" --no-verify
git push --no-verify

🐳 Docker

This project includes an optional production-ready Docker support with development and production configurations.

Quick Start

Development (with hot-reload):

docker-compose up app

Production (optimised build):

docker-compose up app-prod
# or
docker build -t react-starter-kit . && docker run -p 8080:80 react-starter-kit

Development Features

• Hot-reload - Live code updates without rebuilding
• File watching - Automatic polling for Docker compatibility (Mac/Windows)
• Yarn cache - Persistent cache volume for faster installs
• Auto-install - Dependencies installed on container start

Production Features

• Multi-stage builds - Optimized ~25MB final image
• Nginx web server - Production-ready static file serving
• Security hardening:
  • Read-only filesystem
  • No new privileges
  • Minimal attack surface
• Performance optimizations:
  • Gzip compression
  • Immutable asset caching (1 year)
  • No-cache for index.html (instant updates)
• PWA support:
  • Service worker and manifest caching headers
  • CSP configured for PWA features
• Health checks - Container health monitoring endpoint

Environment Variables

The Docker setup automatically configures:

• DOCKER=true - Disables browser auto-open in containers
• CHOKIDAR_USEPOLLING=true - Reliable Vite / Chokidar file watching over bind mounts

PWA in Docker

To test PWA features in Docker development:

# In docker-compose.yml, uncomment:
# - VITE_PWA=true

docker-compose up app

Common Commands

# Development
docker-compose up app              # Start dev server
docker-compose down                # Stop containers
docker-compose logs -f app         # View logs

# Production
docker-compose up app-prod         # Start production preview
docker build -t react-starter-kit . # Build production image
docker images                      # List images
docker ps                          # List running containers

# Cleanup
docker-compose down -v             # Stop and remove volumes
docker system prune                # Clean up unused resources

Dockerfile Details

Build stage:

• Node 18 Alpine base
• BuildKit cache mount for faster rebuilds
• Frozen lockfile for reproducible builds

Production stage:

• Nginx Alpine base
• Custom nginx.conf with:
  • SPA routing fallback
  • Security headers (CSP, X-Frame-Options, etc.)
  • Gzip compression
  • Optimized caching strategy
• Health check endpoint at /health

📁 Project Structure

src/
├── assets/
├── components/
├── contexts/
├── data/
├── hooks/
├── pages/
├── pwa/            # optional
├── routes/
├── sw/             # optional
├── styles/
├── types/
└── utils/

Optional root folder:

api/              # Optional Node API stub (health endpoint, mock APIs, BFF experiments)

Import conventions

• PATHS (and other route constants with no React imports) live in @routes/config/paths. Import from there in components and pages instead of @routes, so you avoid a circular dependency (@routes → router config → layout → header → @routes).
• @components barrel (src/components/index.ts) is convenient for layouts and demos. For large or heavy dependencies, prefer direct imports (for example @components/Button/Button) so tree-shaking stays predictable.

📱 PWA Features

This project includes optional Progressive Web App support with an intelligent opt-in strategy for development.

PWA Capabilities

• Offline support - Works without internet connection
• Install prompts - Add to home screen on mobile/desktop
• Service worker - Automatic caching and updates
• Manifest - App metadata and icons
• Runtime caching - Images, fonts, and API responses

Development Strategy

Default behavior (VITE_PWA=false or unset):

• Service worker not registered
• Manifest link removed from HTML
• No install icon in browser
• Automatic cleanup of existing service workers
• Prevents stale cache confusion during development

Opt-in for testing (VITE_PWA=true):

• Full PWA functionality enabled
• Service worker registers
• Install icon appears
• Test offline behavior and caching

Production:

• PWA always enabled regardless of env var
• Full offline support and caching

Usage

# Regular development (no PWA)
yarn dev

# Test PWA features
VITE_PWA=true yarn dev

# Production (PWA always enabled)
yarn build && yarn preview

Service Worker Cleanup

When switching from VITE_PWA=true to VITE_PWA=false, the app automatically:

1. Unregisters all service workers
2. Removes manifest link from HTML
3. Logs cleanup to console

This prevents stale cache issues and ensures a clean development experience.

🧪 Testing

Optional testing setup using Vitest and React Testing Library.

yarn test
yarn test:run
yarn test:ui
yarn test:coverage

Tests are colocated next to components, hooks, and utilities.

vite.config.ts sets coverage thresholds (lines, functions, statements ≥ 80%; branches ≥ 70%). If you add a lot of untested UI, either cover it with tests or adjust those thresholds to match your team’s bar.

📄 License

MIT — see LICENSE for details.