Next.js Template

A modern Next.js template for building production-ready web applications.

What's Inside

This template provides:

• AGENTS.md — Context instructions for AI agents like Claude Code
• Next.js v16 — App Router, React v19, and React Compiler
• Effect-ts — type-safe functional programming and async effects
• Vercel — hosting and CI deployments
• TypeScript v5 — type safety and enhanced developer experience
• Tailwind CSS v4 — utility-first CSS framework for rapid styling
• Base UI — headless, accessible React components
• Bun — fast package manager and JavaScript runtime
• BiomeJS — linting and formatting for TypeScript, JSON, and CSS
• ESLint — Tailwind class validation and React hooks rules
• Prettier — code formatting for Markdown and YAML files
• Just — command runner for streamlined task automation
• Husky — automated Git hooks with lint-staged

Optimized for developer productivity and application performance.

Note

Some of the configuration files depend upon the Sablier DevKit

Getting Started

Click the Use this template button to create a new repository.

Or clone manually:

git clone https://github.com/PaulRBerg/next-template.git my-app
cd my-app

And then run:

bun install
bun husky
just --list

New to Next.js? Check out these resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.
• Next.js GitHub repository

Prerequisites

• Bun
• Ni
• Just

Usage

Start the development server:

just dev

The dev server starts on a random available port. Check the terminal output for the URL.

Vercel Deployment

Secrets are managed with dotenvx. The encrypted .env is committed to the repo, while the private decryption keys in .env.keys stay local (and out of source control). Set your deployment values with:

na dotenvx set VERCEL_ORG_ID <value>
na dotenvx set VERCEL_PROJECT_ID <value>
na dotenvx set VERCEL_TOKEN <value>

The CI deployment workflow only needs a single GitHub Actions secret, DOTENV_PRIVATE_KEY, which it uses to decrypt .env at deploy time.

Tip

If you use the gh CLI, set the CI secret straight from your local keys file: gh secret set -f .env.keys.

Warning

Cloning this template gives you an encrypted .env you cannot decrypt. Run na dotenvx rotate (or delete .env and .env.keys, then re-run the set commands above) to generate your own keypair before deploying.

Commands

This template uses Just for task automation.

Development

Make sure to run bun install first!

Command	Description
just dev	Start development server
just build	Build for production
just start	Start production server
just clean	Clean build artifacts
just deploy	Deploy to Vercel

Code Quality

Command	Description
just biome-check	Check code with Biome (lint + format)
just biome-write	Auto-fix Biome issues
just eslint-check	Check Tailwind classes and React hooks rules
just eslint-write	Auto-fix ESLint issues
just type-check	Type check with tsgo (falls back to tsc)
just full-check	Run all quality checks
just full-write	Fix all quality issues

Other Commands

Run just to see all available commands, including prettier-*, mdformat-*, and knip-*.

Project Structure

├── .github/workflows/     # GitHub Actions (CI/CD)
├── .husky/                # Git hooks configuration
├── app/                   # Next.js App Router
│   ├── api/health/        # Health check API route
│   ├── globals.css        # Global styles and Tailwind directives
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page
├── lib/                   # Shared utilities
│   ├── cn.ts              # Tailwind class merge utility
│   ├── regex.ts           # Regex utilities
│   └── effect/            # Effect-ts utilities
├── public/                # Static files
├── ui/                    # UI components
│   ├── Button.tsx         # Button component
│   ├── SmartImage.tsx     # Enhanced next/image wrapper
│   └── SmartLink.tsx      # Enhanced next/link wrapper
├── AGENTS.md              # AI agent instructions (CLAUDE.md → symlink)
├── biome.jsonc            # Biome configuration
├── eslint.config.mts      # ESLint configuration (Tailwind + React hooks)
├── justfile               # Just command definitions
├── next.config.ts         # Next.js configuration
├── package.json           # Package configuration
├── postcss.config.mjs     # PostCSS configuration
└── tsconfig.json          # TypeScript configuration

Customization

Styling

Customize the design system by editing:

• app/globals.css — global styles and Tailwind directives
• postcss.config.mjs — PostCSS configuration

Linting and Formatting

Code quality is enforced with Biome (biome.jsonc) and ESLint (eslint.config.mts). ESLint handles Tailwind class validation and React hooks rules that Biome doesn't support yet.

Deployment

Deploy easily with Vercel, the platform from Next.js creators.

See the Next.js deployment documentation for other options.

License

This project is licensed under MIT.