An opinionated, production-ready starter for Single Page Application development with React. Pre-configured tooling, libraries, and a demo app so you can skip the boilerplate and focus on building.
- Vite — fast dev server and build tooling
- TypeScript — strict type safety
- ESLint (with custom rules) + Prettier + Husky — consistent code style
- madge — circular dependency check + module graph visualization
- PNPM — fast, disk-efficient package manager
- Devcontainer — reproducible VS Code dev environment
- GitHub Actions CI — tests, build, coverage reports, deploy draft
- Snyk — dependency (SCA) and source code (SAST) security scanning, with SARIF results in the GitHub Security tab
- SonarCloud — code quality, maintainability, and coverage gating on pull requests
- GitHub Copilot — instructions, skills, and custom prompts (
.github/instructions/,.github/skills/,.github/prompts/) - Claude Code — project rules (
CLAUDE.md), skills, subagents, and custom commands (.claude/)
- Vitest — unit and integration tests
- Storybook — component tests in a real browser
- Playwright — E2E tests across Chromium, Firefox, and WebKit
- Chakra UI — accessible, modular component library
- React Router 7 — routing with strong path typing
- React Query — data fetching and server state synchronization
- Zustand — lightweight state management
- i18next — internationalization
- XState — state orchestration (example usage)
- React Hook Form - form state management with light and composable abstraction
- MSW 2 — API mocking for development and tests
src/ React SPA (features, pages, lib)
server/ Local Fastify API server (dev/demo)
e2e/ Playwright end-to-end tests
- Feature slice architecture with clean architecture principles — each feature has four layers (
components/,application/,providers/,models/) with strict dependency rules - Strict ESLint guardrails enforce the feature-slice layer boundaries. See
eslint.config.mjs. - Circular dependency check and dependency graph visualization via
madge(pnpm madge:circular/pnpm madge:graph) - Centralized API layer with endpoint-based organization and type consolidation
- Spec-driven development for AI-assisted workflows — four-phase gated spec process, typed building block patterns, and a self-improvement loop
- Formatting utilities for numbers, monetary values, and dates
- File naming: PascalCase for React components/stories/page objects, kebab-case for everything else
- A demo app with authentication showcasing the project structure and tooling in action (powered by a local Fastify server in
server/) - Read more:
docs/architecture.md
This project uses spec-driven development for non-trivial features. Instead of prompting an AI agent to "build X," you collaboratively write a short spec (80–150 lines) that constrains intent, design, and sequencing before any code is written.
- Spec workflow — four-phase gated process: Goal & Scope → Design → Sequencing → Review. Each phase requires developer approval before proceeding.
- Building blocks catalog — typed patterns (mutations, queries, stores, components, hooks, models) that specs reference by name. The agent reads the pattern before implementing.
- Self-improvement loop — lessons from past implementations accumulate in
specs/lessons.mdand feed back into future sessions. - Read more:
docs/spec-development-docs.md
Clone the repo and set up your own remote:
git clone --depth 1 https://github.com/bartstc/spa-vite-template.git [project_name]
cd [project_name]
rm -rf .git && git init
git remote add origin git@github.com:username/project.git
It's recommended to run the dev server inside a container for consistent Node/PNPM versions. If you're using VS Code, the included devcontainer config handles this out of the box.
| Command | Description |
|---|---|
pnpm dev |
Dev server with HMR on port 5173 |
pnpm dev:server |
Local API server only on port 3001 |
pnpm dev:all |
Frontend + API server together |
pnpm typecheck |
Type-check all sources without emitting |
pnpm lint |
Check for lint errors |
pnpm madge:circular |
Check for circular module dependencies |
pnpm madge:graph |
Generate dependency graph image (graph.png) — requires graphviz |
pnpm build |
Production build |
pnpm test |
Run all tests (unit + storybook) |
pnpm test:unit |
Unit tests only |
pnpm test:storybook |
Storybook component tests only |
pnpm test:coverage |
Tests with coverage report |
pnpm test:e2e |
E2E tests (headless) |
pnpm test:e2e:ui |
E2E in interactive web UI mode |
pnpm test:e2e:headed |
E2E with visible browser |
pnpm test:e2e:debug |
E2E in debug mode |
pnpm test:e2e:report |
Open the HTML report from the last E2E run |
pnpm storybook |
Storybook on port 6006 |
- Environment: jsdom
- Location: Co-located with source files in
src/ - Run with:
pnpm test:unit
- Environment: Real browser (Chromium) via @vitest/browser-playwright
- Location: Co-located with components in
src/ - Run with:
pnpm test:storybook
- Environment: Chromium, Firefox, and WebKit via @playwright/test
- Location:
e2e/ - Run with:
pnpm test:e2e
This template is opinionated — it picks libraries so you don't have to. If something doesn't fit your project, here's how to strip it out:
| Library | What to remove |
|---|---|
| Chakra UI | src/lib/components/, Chakra provider in src/app/, @chakra-ui/* deps |
| React Router | src/pages/, route config in src/app/, react-router dep |
| React Query | Query provider in src/app/, src/lib/api/ query hooks, @tanstack/react-query deps |
| i18next | src/lib/i18n/, i18n provider in src/app/, i18next + react-i18next deps |
| Zustand | Store files in src/features/*/stores/, zustand dep |
| XState | State machine files (example usage), xstate + @xstate/react deps |
| React Hook Form | src/lib/components/Form/, form components in src/features/*/components/, react-hook-form dep |
| MSW | src/test-lib/handlers/, msw dep, browser/server setup files |
After removing, run pnpm install to clean the lockfile and pnpm lint to catch broken imports.
Note for AI-assisted workflows: Several of these libraries are referenced by name in the building blocks catalog used during spec-driven development. The catalog includes typed patterns for React Query (
query-options-factory,mutation-hook), Zustand (store), and React Hook Form (form). If you remove one of these libraries, also remove or replace its corresponding rule file in.agents/skills/building-blocks/rules/so the agent doesn't generate code for a library that no longer exists in the project.
Open for contributions — bugfixes, new features, and extra modules are welcome.
- Code: Fork the repo, push your changes, and submit a pull request.
- Bugs: Report issues via GitHub Issues.