A modern, type-safe Next.js starter for building web applications with sensible defaults.
Features · Getting started · Project structure · Scripts · Preferred libraries · Deployment · Contributing
- Next.js 16 App Router with React 19 and TypeScript
- Tailwind CSS 4 and shadcn/ui-ready design tokens
- Light and dark themes with
next-themes - Validated, type-safe environment variables with Zod
- Generated metadata, Open Graph image, manifest, sitemap, and
robots.txt - Custom loading, 404, and recoverable error states
- Health-check route at
/api/health - Ultracite linting and formatting powered by Oxlint and Oxfmt
- Lefthook pre-commit, commit-message, and pre-push checks
- Conventional commits with Commitizen and Commitlint
- GitHub Actions CI for linting, type checking, and production builds
- Renovate and Taze dependency update tooling
Create a repository from this template, or clone it directly:
git clone https://github.com/dcrgll/next-template.git my-project
cd my-projectpnpm installThe install step also configures the repository's Git hooks.
Copy the example file and update its values for your environment:
cp .env.example .env.local| Variable | Required | Description |
|---|---|---|
NEXT_PUBLIC_SITE_URL |
Yes | The canonical absolute HTTPS URL for the application. |
NEXT_PUBLIC_* values are inlined at build time. Set NEXT_PUBLIC_SITE_URL in every environment that runs pnpm build.
pnpm devOpen https://dan.local in your browser. To use the standard Next.js development server instead, run pnpm dev:app.
.
├── .github/workflows # Continuous integration
├── src
│ ├── app # App Router pages, metadata, and route handlers
│ │ └── api/health # Readiness endpoint
│ ├── components # Reusable UI components
│ ├── hooks # Shared React hooks
│ ├── lib # Application utilities
│ ├── styles # Global styles and theme tokens
│ └── env.ts # Validated environment contract
├── docs
│ └── PREFERRED_LIBRARIES.md # Preferred stack and dependency guidance
├── AGENTS.md # Agent and project conventions
├── components.json # shadcn/ui configuration
├── lefthook.yml # Local Git hook configuration
└── package.json # Scripts and dependencies
When adding UI, forms, state, data fetching, auth, or related features, follow docs/PREFERRED_LIBRARIES.md. It mirrors the shared preferred-libraries guidance and notes where this template already ships a choice (for example Tailwind, shadcn/ui + Base UI, Phosphor, Zod, and next-themes).
Agent-oriented project conventions live in AGENTS.md, which also points at the preferred libraries list.
| Command | Description |
|---|---|
pnpm dev |
Start Next.js through Portless at dan.local. |
pnpm dev:app |
Start the standard Next.js development server. |
pnpm build |
Create a production build. |
pnpm start |
Run the production server. |
pnpm lint:check |
Check formatting and lint rules. |
pnpm lint |
Apply automatic formatting and lint fixes. |
pnpm typecheck |
Type-check without emitting files. |
pnpm deps:check |
Report available dependency updates. |
pnpm deps:update |
Update dependencies and install them. |
pnpm commit |
Create a conventional commit interactively. |
Run the same checks enforced by CI before opening a pull request:
pnpm lint:check
pnpm typecheck
NEXT_PUBLIC_SITE_URL=https://dan.local pnpm buildDeploy a copy of this repository to Vercel:
During setup, configure NEXT_PUBLIC_SITE_URL with the HTTPS URL Vercel assigns to your production deployment (or your custom domain).
Set NEXT_PUBLIC_SITE_URL to your production HTTPS origin during the build. The generated canonical URLs, social metadata, sitemap, and robots.txt use this value.
The /api/health route returns an uncached 200 response with { "status": "ok" } for deployment readiness checks.
- Create a branch using a conventional prefix such as
feat/,fix/, orchore/. - Prefer libraries and patterns from
docs/PREFERRED_LIBRARIES.md. - Make a focused change and run the quality checks.
- Commit with
pnpm commitor a conventional commit message. - Push the branch and open a pull request against
main.