A minimal starter for static sites: Next.js (App Router), TypeScript (strict), Tailwind CSS, Vitest, Cypress and GitHub Actions. The build is a static export, so any static host can serve it. This README covers Cloudflare Pages.
It deliberately has no i18n, auth, database or UI library.
On GitHub, click Use this template to create a new repository. (To turn your own copy into a template: Settings > General > Template repository.)
Then update the site name and description in src/app/layout.tsx, and replace
src/app/icon.svg and src/app/opengraph-image.png.
- Node.js 24 (see
.nvmrc; with nvm, runnvm use) - npm
npm install
cp .env.example .env.local
npm run devOpen http://localhost:3000.
| Variable | Required | Description |
|---|---|---|
NEXT_PUBLIC_SITE_URL |
Yes | Public URL of the site, used for SEO and the sitemap |
src/lib/env.ts validates the variables with Zod. If a value is missing or
invalid, the build fails with a clear message. The values are inlined at build
time, so a change requires a new build.
| Script | What it does |
|---|---|
npm run dev |
Start the dev server |
npm run build |
Build the static site to out/ |
npm start |
Serve out/ on port 3000 (run build first) |
npm run lint |
Run ESLint |
npm run lint:secrets |
Scan files for leaked secrets with secretlint |
npm run typecheck |
Run the TypeScript compiler without output |
npm test |
Run unit tests with Vitest |
npm run test:watch |
Run Vitest in watch mode |
npm run test:e2e |
Build, serve out/ and run the Cypress smoke test |
npm run format |
Format all files with Prettier |
- Unit and component tests: Vitest and Testing Library. Put a test file
next to the code it tests, named
*.test.ts(x). Runnpm test. - End-to-end tests: Cypress in
cypress/e2e/.npm run test:e2eruns the tests against the production build, which is the same output that is deployed. To debug in the browser, runnpm run build && npm start, and in a second terminal runnpx cypress open.
A pre-commit hook (Husky and lint-staged) runs secretlint, ESLint and
Prettier on staged files. CI runs two parallel jobs on each pull request:
verify (lint, secret scan, typecheck, unit tests, build) and e2e (Cypress
against the static build).
src/
app/ Routes, layout, metadata, tokens.css, icon, OG image, sitemap, robots
components/ Reusable UI components and their tests
lib/ Logic without UI (env validation, helpers)
cypress/e2e/ End-to-end tests
.github/ CI workflow, Dependabot, PR and issue templates
src/app/tokens.css defines colors as CSS variables for light and dark mode.
Dark mode follows the operating system setting (prefers-color-scheme).
globals.css maps the variables to Tailwind utilities such as bg-bg,
text-fg and bg-accent. Use these utilities instead of hard-coded colors.
- Push the repository to GitHub.
- In the Cloudflare dashboard, go to Workers & Pages > Create > Pages > Connect to Git, and select the repository.
- Set the build settings:
- Framework preset: None
- Build command:
npm run build - Build output directory:
out
- Under Environment variables, add
NEXT_PUBLIC_SITE_URLwith your production URL (for examplehttps://my-site.pages.dev). - Click Save and Deploy.
Cloudflare reads the Node.js version from .nvmrc. Each push to main
deploys to production. Each pull request gets a preview URL.
Notes:
- Do not use the
@cloudflare/next-on-pagesadapter. This site is plain static files and needs no adapter. - Cloudflare serves
out/about.htmlat/about, so routes work withouttrailingSlash. - Features that need a server (API routes, middleware, server actions, ISR, default image optimization) do not work with a static export.
Never commit secrets. Put them in .env.local, which is gitignored.
- secretlint blocks a commit that contains a known secret format (API
keys, tokens, private keys). CI runs the same scan on every pull request.
It ignores
.env*files except.env.example. - GitHub secret scanning and push protection reject a push with a known secret. They are free for public repositories. Private repositories need GitHub Secret Protection (paid), so secretlint is the free layer that always runs.
If a secret reaches a commit, rotate it first (the old value is compromised), then remove it from the history.