A starter template for building React single-page apps with TypeScript and Vite — including Biome-based linting/formatting, a two-tier E2E test setup, optional frontend telemetry, and CI/CD to GitHub Pages.
Live demo: https://ks6088ts.github.io/template-typescript-react/
- ⚡️ Vite dev server with HMR and optimized production builds
- ⚛️ React 19 + TypeScript
- 🧹 Biome for linting and formatting (plus
actionlintfor workflows) - 🧪 Vitest (browser mode) + Playwright E2E suites
- 📊 Optional OpenTelemetry / Application Insights frontend telemetry
- 🐳 Local Grafana LGTM observability stack via Docker Compose
- 🚀 GitHub Actions CI/CD with GitHub Pages deployment
| Technology | Role |
|---|---|
| TypeScript | Static typing |
| React 19 | UI library |
| Vite | Build tool & dev server |
| pnpm | Package manager |
| Biome | Linting and formatting |
| Vitest (browser mode) | Component / integration tests |
| Playwright | E2E smoke tests |
| OpenTelemetry / Application Insights | Optional telemetry |
| Docker Compose + Grafana LGTM | Local observability |
| GitHub Actions / GitHub Pages | CI/CD & hosting |
See docs/tech-stack.md for an overview of each technology, its purpose, and the rationale for adoption.
Prerequisites: Node.js and pnpm.
# Install dependencies
pnpm install
# Start the dev server (http://localhost:5173)
pnpm dev
# Build for production
pnpm build
# Preview the production build
pnpm preview
# Lint
pnpm lint
# Format
pnpm formatA Makefile wraps common workflows — run make help to list targets (e.g. make ci-test, make e2e, make ci-test-e2e).
Build and run the production nginx image locally:
# Build the production image
make docker-build
# Run the container (http://localhost:8080)
make docker-runYou can also start the same image with Docker Compose:
docker compose -f docker/compose.yaml up --build webFor Docker-focused CI checks, run:
make ci-test-dockerPushing a v* tag keeps the existing release asset flow and also publishes multi-arch (linux/amd64, linux/arm64) images to both registries:
| Registry | Image | Workflow |
|---|---|---|
| GitHub Container Registry | ghcr.io/ks6088ts/template-typescript-react |
ghcr-release.yaml |
| Docker Hub | ks6088ts/template-typescript-react |
docker-release.yaml |
# Pull and run from GitHub Container Registry
docker run --rm -p 8080:80 ghcr.io/ks6088ts/template-typescript-react:latest
# Pull and run from Docker Hub
docker run --rm -p 8080:80 ks6088ts/template-typescript-react:latestThe Docker Hub workflow requires two repository secrets: DOCKERHUB_USERNAME and DOCKERHUB_TOKEN (a Docker Hub access token).
Two E2E suites run headless by default — Vitest browser mode and Playwright:
pnpm exec playwright install chromium
pnpm e2eSet E2E_HEADED=true to watch the browser UI. See docs/e2e-testing.md for details.
Frontend telemetry is optional and opt-in via environment variables, supporting Application Insights and OpenTelemetry with a local Grafana stack. It is a no-op when unconfigured. See docs/telemetry.md.
- Tech Stack — adopted technologies, purpose, and rationale
- Frontend Telemetry — Application Insights / OpenTelemetry setup
- E2E Testing — Vitest browser & Playwright suites
- Using Biome — linting, formatting, and customization
src/ # React app source
telemetry/ # Telemetry providers, config, and React bindings
__tests__/e2e/ # Vitest browser E2E tests
playwright/ # Playwright smoke tests
docker/ # OTel Collector + Grafana LGTM stack
Dockerfile # Production nginx image for built SPA assets
docs/ # Detailed documentation
.github/workflows/ # CI/CD pipelines