SPA Vite Template

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.

What's included

Developer experience

• 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/)

Testing

• Vitest — unit and integration tests
• Storybook — component tests in a real browser
• Playwright — E2E tests across Chromium, Firefox, and WebKit

Libraries

• Chakra UI — accessible, modular component library
• React Router 8 — 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

Architecture

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

AI-assisted development

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.md and feed back into future sessions.
• Read more: docs/spec-development-docs.md

Getting started

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

Dev environment

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.

Commands

Testing strategy

Unit tests (*.test.ts, *.test.tsx)

• Environment: jsdom
• Location: Co-located with source files in src/
• Run with: pnpm test:unit

Component tests (*.stories.tsx)

• Environment: Real browser (Chromium) via @vitest/browser-playwright
• Location: Co-located with components in src/
• Run with: pnpm test:storybook

E2E tests (*.spec.ts)

• Environment: Chromium, Firefox, and WebKit via @playwright/test
• Location: e2e/
• Run with: pnpm test:e2e

Removing libraries you don't need

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:

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.

Contributing

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.

License

MIT