Skip to content
Public template

About

Minimal starter for static sites: Next.js App Router, TypeScript strict, Tailwind CSS, Vitest, Cypress and GitHub Actions. Static export for any host.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

31 Commits

Folders and files

Repository files navigation

Next.js Template

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.

Use this template

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.

Requirements

  • Node.js 24 (see .nvmrc; with nvm, run nvm use)
  • npm

Run locally

npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3000.

Environment variables

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.

Scripts

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

Test

  • Unit and component tests: Vitest and Testing Library. Put a test file next to the code it tests, named *.test.ts(x). Run npm test.
  • End-to-end tests: Cypress in cypress/e2e/. npm run test:e2e runs the tests against the production build, which is the same output that is deployed. To debug in the browser, run npm run build && npm start, and in a second terminal run npx 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).

Project structure

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

Theming

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.

Deploy to Cloudflare Pages

  1. Push the repository to GitHub.
  2. In the Cloudflare dashboard, go to Workers & Pages > Create > Pages > Connect to Git, and select the repository.
  3. Set the build settings:
    • Framework preset: None
    • Build command: npm run build
    • Build output directory: out
  4. Under Environment variables, add NEXT_PUBLIC_SITE_URL with your production URL (for example https://my-site.pages.dev).
  5. 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-pages adapter. This site is plain static files and needs no adapter.
  • Cloudflare serves out/about.html at /about, so routes work without trailingSlash.
  • Features that need a server (API routes, middleware, server actions, ISR, default image optimization) do not work with a static export.

Secrets

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.

About

Minimal starter for static sites: Next.js App Router, TypeScript strict, Tailwind CSS, Vitest, Cypress and GitHub Actions. Static export for any host.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages