Production-oriented React + TypeScript starter: Vite, TanStack Router/Query, Tailwind CSS 4, i18next (ru / en / uz), Vitest, and a Docker + nginx image with runtime environment variables — build the image once, configure it at container start.
- React 19 / TypeScript 5 (strict) / Vite 7
- TanStack Router — type-safe, code-based routing with lazy-loaded pages
- TanStack Query — server state, typed fetch client, query-key factory
- Tailwind CSS 4 + shadcn/ui primitives — dark mode via the
.darkclass - i18next (react-i18next + browser language detector) — ru / en / uz
- Vitest + Testing Library — jsdom, V8 coverage
- ESLint (TanStack config) + Prettier — no semicolons, single quotes
- Docker — multi-stage
node:24-alpinebuild →nginx:1.29-alpineserve (both pinned by digest) - GitHub Actions — CI gate, GHCR image publishing, optional deploy
├── src/
│ ├── app/ # Wiring: providers, router, routes, devtools
│ ├── pages/ # Route screens: HomePage, AboutPage, NotFoundPage
│ ├── widgets/ # Self-contained page blocks: header
│ ├── features/ # User interactions: language-switcher, theme-switcher
│ ├── entities/ # Business data + its API: health
│ ├── shared/ # api client, ui, shadcn-ui, lib, locales, styles, constants, types
│ ├── test/ # Vitest setup + render helpers
│ ├── env.ts # Typed env access (runtime → build-time → default)
│ ├── i18n.ts # i18next initialization
│ └── main.tsx # Entry point
├── public/ # Static assets; env-config.js dev fallback
├── docker/ # 90-env-config.sh — runtime env injection at container start
├── nginx/ # nginx.conf: SPA fallback, caching, /healthz
├── docs/ # architecture.md · runtime-env.md · deploy.md
├── .github/workflows/ # ci.yml · build-push.yml · deploy.yml
├── docker-compose.yml # Local production-like (builds from source)
├── docker-compose.prod.yml # Production deploy (pulls the registry image)
├── Dockerfile
└── Makefile
The src/ layering (a pragmatic Feature-Sliced Design) and the import-direction rule are
described in docs/architecture.md.
Local development:
nvm use # Node 24 (.nvmrc)
npm ci
npm run dev # → http://localhost:3000Docker (production-like, builds from source):
make env # create .env from .env.example (never overwrites an existing one)
make up # build the image + serve via nginx → http://localhost:${APP_PORT:-3000}All variables live in .env.example; make env copies it to .env.
| Variable | Default | Description |
|---|---|---|
APP_PORT |
3000 |
Host port the container publishes (docker-compose*.yml → nginx :80) |
FRONTEND_IMAGE |
ghcr.io/igorkhaylov/react-template:latest |
Image docker-compose.prod.yml pulls; pin :sha-<full-sha> for reproducible deploys |
VITE_API_BASE_URL |
http://localhost:8000 |
Backend API base URL used by the fetch client |
VITE_APP_NAME |
MyApp |
App name shown in the header |
VITE_DEFAULT_LOCALE |
ru |
i18next fallback language (ru / en / uz) |
A Vite SPA normally bakes VITE_* values into the bundle at build time — one build per
environment. This template avoids that for Docker: the image is built once and configured
at container start.
- Docker image (runtime):
nginx:alpinerunsdocker/90-env-config.shfrom/docker-entrypoint.d/before nginx starts. It writes whitelistedVITE_*container env vars intoenv-config.js, whichindex.htmlloads before the app bundle aswindow.__ENV__. Changing a value needs a container restart, not a rebuild. - Plain
npm run build(build-time): without Docker, values are baked in from the Vite.envfiles as usual — a different value means a rebuild.
src/env.ts resolves every key as
window.__ENV__ → import.meta.env → default. Only whitelisted, non-secret values are
exposed — everything here is public to the browser. Full mechanism, how to add a variable,
and the security notes: docs/runtime-env.md.
| Script | What it does |
|---|---|
npm run dev |
Vite dev server with HMR on port 3000 |
npm run build |
Production build to dist/ (types are gated by typecheck / CI) |
npm run preview |
Serve the built dist/ locally |
npm run typecheck |
TypeScript check, no emit |
npm run lint |
ESLint |
npm run lint:fix |
ESLint with auto-fix |
npm run format |
Prettier, write |
npm run format:check |
Prettier, check only |
npm run test |
Vitest, single run |
npm run test:watch |
Vitest watch mode |
npm run coverage |
Vitest with V8 coverage (text + html reports) |
npm run check |
Non-mutating gate: format:check + lint + typecheck + test |
make help prints the same summary. Local targets delegate to the npm scripts above.
| Group | Targets |
|---|---|
| First run | env (create .env) · install (npm ci) |
| Local dev | start · lint · lint-fix · format · typecheck · test · check · preview |
| Docker | up · down · down-v · build · pull · logs [service] · restart · bash |
| Server | make prod deploy — pull the registry image and (re)start (never builds) |
| Utilities | push (manual multi-platform image push) · clean |
The prod prefix switches the compose file: prod → docker-compose.prod.yml (pulls the
prebuilt image), no prefix → docker-compose.yml (builds from source).
Vitest + Testing Library on jsdom; globals: true, setup in
src/test/setup.ts (cleanup + vi.unstubAllGlobals/Envs after each
test). Tests are colocated with the code (*.test.ts(x)).
npm run test # single run
npm run test:watch # watch mode
npm run coverage # what CI runs: V8 coverage + thresholds (coverage/ is gitignored)src/test/utils.tsx provides renderWithProviders (isolated
QueryClient + i18n instance), renderWithRouter (memory-history router), and
fakeResponse for testing the API client without a network.
- ESLint —
eslint.config.js:@tanstack/eslint-config(type-aware) +eslint-config-prettier, plus a few explicit rules (no-consolewarns). - Prettier —
prettier.config.js: no semicolons, single quotes, width 100, Tailwind class sorting viaprettier-plugin-tailwindcss. - TypeScript — strict mode plus
noUncheckedIndexedAccess,noUnusedLocals/noUnusedParameters,@/*→src/*alias.
npm run check runs everything non-mutating — the same gates CI runs (CI additionally
verifies the production build with npm run build).
i18next with ru, en, uz (translations in src/shared/locales/).
The language detector reads localStorage first, then the browser language; every explicit
switch is persisted back to localStorage. The fallback language comes from
VITE_DEFAULT_LOCALE.
To add a locale:
- Create
src/shared/locales/<lng>.json(copyen.jsonand translate — the locale-parity test insrc/i18n.test.tsdiscovers locale files automatically and fails if any key set differs). - Add the code to
LOCALESinsrc/shared/constants/common.ts. - Register it in
resourcesinsrc/i18n.ts.
The language switcher renders from LOCALES automatically.
Dark mode uses Tailwind's class strategy: the .dark class on <html> (wired via
@custom-variant dark in src/shared/styles/global.css).
All colors are CSS variables defined for :root and .dark, so shadcn/ui components theme
automatically. initTheme() runs synchronously before React mounts (no flash): stored
choice from localStorage first, OS prefers-color-scheme otherwise.
A minimal typed fetch client (src/shared/api/client.ts) — no
runtime dependencies: JSON handling, query params, AbortSignal passthrough, and a typed
ApiError for every non-2xx response. Each entity owns its API functions and TanStack Query
hooks (src/entities/<name>/api.ts + queries.ts), with query keys from the
createQueryKeys factory. Conventions: docs/architecture.md.
The home page ships a backend status card that polls GET /healthcheck/ and
demonstrates the layer end to end (pending → success → error states). It pairs with
django-template out of the box — start
that backend (or point VITE_API_BASE_URL at any API with a /healthcheck/ endpoint) and
the card turns green. The "no backend" state is expected, not an error: the template runs
standalone.
.github/workflows/ci.yml— the quality gate, defined once:npm audit(prod deps, high+) →format:check→lint→typecheck→coverage(tests + thresholds) →build. Runs on every pull request, and build-push.yml calls it (workflow_call) before publishing — which is what gates pushes tomaster..github/workflows/build-push.yml— on push tomaster, onv*tags, or manual: runs the quality gate, builds the multi-arch (amd64+arm64) Docker image, pushes it to GHCR (ghcr.io/<owner>/<repo>) with tagslatest(default branch),sha-<full-sha>(every build — use this to pin prod), andvX.Y.Z/X.Y.Z(git tags), then scans the pushed image with Trivy (fails on fixable high/critical CVEs). Needs no secrets beyond the built-inGITHUB_TOKEN..github/workflows/deploy.yml— optional, manual dispatch only, requires a self-hosted runner on the target server. Picks a GitHub Environment (dev/prod), writes.envfrom that environment'sENV_FILEsecret, runsdocker compose -f docker-compose.prod.yml pull && up -d, then waits until the container healthcheck reports healthy (a crashlooping deploy fails the run). If you deploy by SSH-ing in and runningmake prod deploy, delete it or leave it unused..github/dependabot.yml— weekly update PRs for npm packages (minor+patch grouped), GitHub Actions versions and Docker base-image digests.
Production uses a registry image, not a server-side build: CI pushes the image to GHCR, the server only pulls it.
# On the server (needs: docker-compose.prod.yml + Makefile + ./.env):
make prod deploy # = docker compose -f docker-compose.prod.yml pull && up -dSet FRONTEND_IMAGE in the server's .env — pin a reproducible build by sha, e.g.
ghcr.io/igorkhaylov/react-template:sha-<full-sha> (a moving :latest also works but
drifts on the next push). GHCR packages are private by default, so the server must be
logged in to the registry first. The full zero-to-first-deploy runbook, including the
GHCR token setup and rollback, is in docs/deploy.md.
The container serves on port 80 (published as APP_PORT), answers GET /healthz with 204
for health checks, and is expected to sit behind your edge reverse proxy (TLS termination).
- Name the app:
VITE_APP_NAMEin.env/.env.example,nameanddescriptioninpackage.json,<title>+meta descriptioninindex.html, andpublic/manifest.json. - Replace the icon:
public/favicon.svg. - Point at your registry:
FRONTEND_IMAGEin.env.exampleand theIMAGEdefault in theMakefile;GITHUB_URLinsrc/pages/HomePage.tsx. - Replace the health demo: swap
src/entities/healthand theBackendStatusCardinHomePage.tsxfor your first real entity — they exist to be copied. - Prune locales: drop unneeded languages from
LOCALES,src/i18n.tsandsrc/shared/locales/; setVITE_DEFAULT_LOCALE. - Rewrite the pages:
HomePage/AboutPageare template showcases.
- docs/architecture.md — layering, import rules, routing and data-fetching conventions, where new code goes
- docs/runtime-env.md — the runtime env mechanism end to end
- docs/deploy.md — server runbook: zero → first deploy → CI