Next.js 16 Starter Documentation

Introduction

This starter template is built with the latest web technologies to help you create fast, modern, and production-ready applications. It combines the power of Next.js 16 with React 19, shadcn/ui components, and Tailwind CSS v4.

Philosophy

This starter follows key principles to ensure code quality and maintainability:

• Type Safety First - Full TypeScript support with strict mode
• Theme-Based Design - All colors use CSS variables for light/dark mode
• Mobile-First Responsive - Designed for all screen sizes
• Server Components by Default - Leverage React 19 Server Components
• Accessibility - WCAG compliant components from shadcn/ui

Tech Stack

Core Framework

• Next.js 16.0.0-beta.0 - App Router with Turbopack
• React 19.1.0 - New JSX transform and Server Components
• TypeScript 5 - Strict mode enabled

Styling

• Tailwind CSS v4 - Latest version with PostCSS
• shadcn/ui - Beautifully designed components (New York style)
• CVA - Class Variance Authority for component variants
• Lucide React - Modern icon library

Build Tools

• Turbopack - Next.js built-in bundler
• Bun - Fast package manager and runtime
• ESLint - Code quality and consistency

Getting Started

Prerequisites

Make sure you have Bun installed on your system:

curl -fsSL https://bun.sh/install | bash

Installation

Clone and install dependencies:

git clone <your-repo>
cd next16
bun install

Development

Start the development server with Turbopack:

bun dev

Open http://localhost:3000 in your browser.

Build for Production

bun build
bun start

Development Workflow

Adding shadcn/ui Components

Use the shadcn CLI to add components:

bunx shadcn@latest add button

Components are installed to components/ui/ and can be imported:

import { Button } from "@/components/ui/button"

Server vs Client Components

Use Server Components by default:

// Server Component (default)
export function StaticContent() {
  return <div>Static content</div>
}

Add "use client" only when needed:

"use client"

import { useState } from "react"

export function InteractiveContent() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

Async APIs in Next.js 16

Remember that cookies, headers, and params are now async:

// ✅ Next.js 16 (correct)
const cookieStore = await cookies()
const headersList = await headers()

// ❌ Next.js 15 syntax (doesn't work in v16)
const cookieStore = cookies()
const headersList = headers()

Environment & Configuration

Environment Variables

Create a .env.local file in the root directory:

# Example environment variables
NEXT_PUBLIC_APP_URL=http://localhost:3000
DATABASE_URL=your-database-url
OPENAI_API_KEY=your-api-key

Path Aliases

The project uses TypeScript path aliases configured in tsconfig.json:

• @/components - React components
• @/components/ui - shadcn/ui components
• @/lib - Utility functions
• @/hooks - Custom React hooks

Project Structure

next16/
├── app/                    # App Router pages and layouts
│   ├── (marketing)/        # Marketing route group
│   │   ├── page.tsx        # Home page
│   │   └── docs/           # Documentation
│   ├── layout.tsx          # Root layout
│   └── globals.css         # Global styles
├── components/             # React components
│   └── ui/                 # shadcn/ui components
├── lib/                    # Utility functions
│   └── utils.ts            # cn() helper
├── hooks/                  # Custom React hooks
├── LLMS/                   # Documentation and guides
├── components.json         # shadcn/ui configuration
├── next.config.ts          # Next.js configuration
├── tsconfig.json           # TypeScript configuration
└── package.json            # Dependencies and scripts

UI & Styling

Theme Tokens

Always use theme tokens, never hardcoded colors:

// ✅ Good - Uses theme tokens
<div className="bg-background text-foreground">
<button className="bg-primary text-primary-foreground hover:bg-primary/90">

// ❌ Bad - Hardcoded colors
<div className="bg-white dark:bg-black text-black dark:text-white">
<button className="bg-blue-500 hover:bg-blue-600">

Available Theme Tokens

• bg-background / text-foreground - Main background and text
• bg-card / text-card-foreground - Card backgrounds
• bg-primary / text-primary-foreground - Primary buttons
• bg-secondary / text-secondary-foreground - Secondary buttons
• text-muted-foreground - Secondary/muted text
• border-border - Default borders

Responsive Padding Pattern

Use consistent responsive padding:

// ✅ Good
<div className="px-4 sm:px-6 lg:px-8">

// ❌ Bad - Inconsistent padding
<div className="px-16">

Conditional Classes

Always use the cn() utility:

import { cn } from "@/lib/utils"

<div className={cn(
  "base-classes",
  isActive && "active-classes",
  className
)}>

Scripts & Tooling

Available Scripts

• bun dev - Start development server with Turbopack
• bun build - Build for production
• bun start - Start production server
• bun lint - Run ESLint

Adding Dependencies

bun add <package>           # Production dependency
bun add -d <package>        # Development dependency
bun remove <package>        # Remove dependency