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

To make the CI deployment workflow work, you have to configure these environment variables in your GitHub Actions
secrets:

• VERCEL_ORG_ID
• VERCEL_PROJECT_ID
• VERCEL_TOKEN

[!TIP]

If you use the gh CLI, you can put your environment variables in a .env file and then
run this command: gh secret set -f .env.

Commands

This template uses Just for task automation.

Development

Make sure to run bun install first!

Code Quality

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.