Next.js Style Guide

Linting

Next.js 16 removed the next lint command, and next build no longer runs linting. Projects MUST invoke the linter directly and MUST run it as a separate CI step.

Configuration

@next/eslint-plugin-next ships flat config by default in Next.js 16.

npm install --save-dev eslint@9.39.5 eslint-config-next@16.3.4

ESLint MUST be pinned to the 9.x line. eslint-config-next@16.3.4 bundles eslint-plugin-react@^7.37.0, which uses the pre-ESLint-10 rule context API; under eslint@10.10.0 every lint run aborts with TypeError: Error while loading rule 'react/display-name': contextOrFilename.getFilename is not a function.

// eslint.config.mjs
import { defineConfig, globalIgnores } from 'eslint/config';
import nextVitals from 'eslint-config-next/core-web-vitals';

export default defineConfig([
  ...nextVitals,
  globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts']),
]);

// package.json
{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  }
}

Don’t — removed in Next.js 16, and no substitute runs during next build:

{
  "scripts": {
    "lint": "next lint"
  }
}

Do — the linter runs on its own, in its own CI step:

{
  "scripts": {
    "lint": "eslint ."
  }
}

Projects that use Biome as their linter MUST run biome check . instead and MUST NOT expect Next.js-specific rules from it; @next/eslint-plugin-next has no Biome equivalent.

The eslint key in next.config.ts was removed alongside the command and MUST be deleted during upgrades.

Project Structure

Projects MUST use the App Router directory structure:

my-app/
├── app/
│   ├── layout.tsx              # Root layout
│   ├── page.tsx                # Home page
│   ├── globals.css
│   ├── (marketing)/            # Route group (URL-less)
│   │   ├── about/
│   │   │   └── page.tsx
│   │   └── layout.tsx
│   ├── dashboard/
│   │   ├── page.tsx
│   │   ├── loading.tsx         # Loading UI
│   │   ├── error.tsx           # Error boundary
│   │   └── settings/
│   │       └── page.tsx
│   └── api/
│       └── users/
│           └── route.ts        # API route handler
├── components/
│   ├── ui/                     # Reusable UI components
│   │   ├── button.tsx
│   │   └── card.tsx
│   └── features/               # Feature-specific components
│       └── user-profile.tsx
├── lib/
│   ├── db.ts                   # Database client
│   ├── actions.ts              # Server Actions
│   └── utils.ts                # Utilities
├── public/
│   ├── images/
│   └── fonts/
├── middleware.ts               # Edge middleware
├── next.config.ts
├── tsconfig.json
└── package.json

Why: The App Router co-locates routes with their components, making the file system the API. Route groups organize pages without affecting URLs, and special files (loading.tsx, error.tsx) provide consistent UX patterns.

File-Based Routing

Routes MUST be defined using the file system conventions:

// app/page.tsx - Home page at /
export default function HomePage() {
  return <h1>Home</h1>;
}

// app/blog/page.tsx - Blog index at /blog
export default function BlogPage() {
  return <h1>Blog</h1>;
}

// app/blog/[slug]/page.tsx - Dynamic route at /blog/:slug
export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>Post: {slug}</h1>;
}

// app/blog/[...slug]/page.tsx - Catch-all route at /blog/*
export default async function BlogCatchAll({
  params,
}: {
  params: Promise<{ slug: string[] }>;
}) {
  const { slug } = await params;
  return <h1>Path: {slug.join('/')}</h1>;
}

Asynchronous Request APIs

params, searchParams, cookies(), headers(), and draftMode() are promises. Next.js 15 accepted synchronous access with a deprecation warning; Next.js 16 removed that compatibility layer. Every consumer MUST await them.

Don’t — params is a promise, so params.slug is undefined:

export default function BlogPostPage({
  params,
}: {
  params: { slug: string };
}) {
  return <h1>Post: {params.slug}</h1>;
}

Do:

export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>Post: {slug}</h1>;
}

Why: A Route Handler with a synchronous params type fails the build with TS2344. A page does not: it compiles, renders, and silently substitutes undefined for every dynamic segment. The failure is invisible until production output is inspected.

Client Components cannot be async. They MUST unwrap the promise with React’s use hook:

// app/blog/[slug]/tag-filter.tsx
'use client';

import { use } from 'react';

export function TagFilter({
  searchParams,
}: {
  searchParams: Promise<{ tag?: string }>;
}) {
  const { tag } = use(searchParams);
  return <span>Filtering by: {tag ?? 'all'}</span>;
}

Projects SHOULD run npx next@16.3.4 typegen and use the generated PageProps, LayoutProps, and RouteContext helpers instead of hand-writing the promise types:

// app/blog/[slug]/page.tsx
export default async function BlogPostPage(props: PageProps<'/blog/[slug]'>) {
  const { slug } = await props.params;
  return <h1>Post: {slug}</h1>;
}

Why: File-based routing eliminates routing configuration, makes page discovery intuitive, and enables automatic code splitting per route.

Route Groups and Parallel Routes

Projects SHOULD use route groups for organization:

app/
├── (marketing)/
│   ├── layout.tsx        # Marketing layout
│   ├── about/page.tsx
│   └── pricing/page.tsx
├── (app)/
│   ├── layout.tsx        # App layout (with auth)
│   ├── dashboard/page.tsx
│   └── settings/page.tsx
└── @modal/               # Parallel route (named slot)
    └── login/page.tsx

// app/(app)/layout.tsx - Layout for app routes
export default function AppLayout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <div>
      <nav>App Navigation</nav>
      {children}
      {modal}
    </div>
  );
}

Why: Route groups organize files without adding URL segments. Parallel routes enable advanced patterns like modals, split views, and conditional rendering.

Server vs Client Components

Components MUST be Server Components by default. Client Components MUST be explicitly marked with 'use client'.

// app/components/user-profile.tsx - Server Component (default)
import { getUser } from '@/lib/db';

export default async function UserProfile({ userId }: { userId: string }) {
  const user = await getUser(userId); // Direct database access

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

// app/components/counter.tsx - Client Component
'use client';

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

Partial Prerendering and Cache Components

Next.js 16 removed the experimental Partial Prerendering⁸ controls. Projects MUST NOT set experimental.ppr and MUST NOT export experimental_ppr from a route segment. Partial Prerendering is now the default App Router behavior once Cache Components is enabled, which projects SHOULD do:

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  cacheComponents: true,
};

export default nextConfig;

Don’t — next build aborts on Next.js 16 with experimental.ppr` has been merged into `cacheComponents:

const nextConfig: NextConfig = {
  experimental: {
    ppr: 'incremental',
  },
};

There is no per-route opt-in any more. With cacheComponents enabled, data fetching is dynamic by default, every route gets a prerendered static shell, and you choose what to cache:

// app/dashboard/page.tsx
import { Suspense } from 'react';
import { UserGreeting } from './user-greeting';
import { RecentActivity } from './recent-activity';

// Static shell renders immediately, dynamic parts stream in
export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>  {/* Static - part of the prerendered shell */}

      <Suspense fallback={<div>Loading user...</div>}>
        <UserGreeting />  {/* Request-time data - streams in */}
      </Suspense>

      <Suspense fallback={<div>Loading activity...</div>}>
        <RecentActivity />  {/* Request-time data - streams in */}
      </Suspense>
    </div>
  );
}

Cache a component or function with the use cache directive, and give it a lifetime and invalidation tags:

// app/dashboard/popular-posts.tsx
import { cacheLife, cacheTag } from 'next/cache';
import { getPopularPosts } from '@/lib/db';

export async function PopularPosts() {
  'use cache';
  cacheLife('hours');
  cacheTag('posts');

  const posts = await getPopularPosts();

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

A use cache scope MUST NOT read cookies(), headers(), params, or searchParams; doing so throws next-request-in-use-cache. Read those outside the cached scope and pass the values in as arguments, which also makes them part of the cache key.

cacheLife and cacheTag are stable in Next.js 16 and MUST be imported without the unstable_ prefix.

Enabling Cache Components Is a Breaking Change

Once cacheComponents is on, every route that reads request data at the top level fails the build:

Error: Route "/dashboard": Next.js encountered uncached or runtime data during
prerendering. `fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`,
or `connection()` accessed outside of <Suspense> prevents the route from being
prerendered.

Each such route MUST take one of three options:

Option	How	Use when
Stream	Move the read into a child inside <Suspense fallback={...}>	The shell is useful without that data
Cache	Wrap the read in use cache and pass request values as arguments	The result is shareable between requests
Block	export const instant = false	The whole page is meaningless without the data

The route-segment exports dynamic, revalidate, and dynamicParams are rejected outright: Route segment config "dynamicParams" is not compatible with nextConfig.cacheComponents.

Why: Traditional SSR waits for all data before sending HTML. Partial Prerendering sends a static shell instantly (best TTFB) while streaming dynamic content as it resolves, giving the speed of static sites with the personalization of dynamic pages. Cache Components replaces the removed per-route flag with an explicit, composable choice of what is cached and for how long.

Projects that have not adopted Cache Components MAY continue to use the route-segment caching model described under Static Site Generation (SSG) and ISR; it remains supported.

Data Fetching in Server Components

Server Components MUST fetch data using async/await:

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation';
import { getPost } from '@/lib/db';

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);

  if (!post) {
    notFound(); // Renders 404 page
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  );
}

// Generate static params at build time
export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

Fetch Caching and Revalidation

Projects MUST configure caching behavior explicitly:

// Static data (cached indefinitely)
const response = await fetch('https://api.example.com/data');

// Revalidate every 60 seconds
const response = await fetch('https://api.example.com/data', {
  next: { revalidate: 60 },
});

// Never cache (always fresh)
const response = await fetch('https://api.example.com/data', {
  cache: 'no-store',
});

// Revalidate on-demand via tag
const response = await fetch('https://api.example.com/data', {
  next: { tags: ['posts'] },
});

// app/actions.ts - Revalidate tagged data
'use server';

import { revalidatePath, updateTag } from 'next/cache';

export async function updatePost(id: string) {
  await db.posts.update({ id });
  updateTag('posts'); // Expire now and refresh in the same request
  revalidatePath('/blog'); // Revalidate /blog route
}

Why: Explicit cache control balances performance with data freshness. Tag-based revalidation enables surgical cache invalidation without rebuilding the entire site.

Tag Invalidation APIs

Next.js 16 made the profile argument of revalidateTag mandatory. Calls MUST select the API that matches the consistency the caller needs:

API	Semantics	Use when
updateTag(tag)	Expires and refreshes in the same request	A Server Action whose user must see their own write
revalidateTag(tag, 'max')	Stale-while-revalidate for up to a year	Content where a short delay is acceptable
revalidateTag(tag, { expire: 0 })	Next read blocks on a cache miss	A Route Handler or webhook that needs the data gone now

updateTag is available only inside Server Actions. Route Handlers MUST use revalidateTag with an explicit profile.

Don’t — fails to compile with TS2554: Expected 2 arguments, but got 1:

revalidateTag('posts');

Do:

// Server Action: the editor sees their own change immediately
updateTag('posts');

// Anywhere: readers get stale content while the refresh runs
revalidateTag('posts', 'max');

// Webhook Route Handler: drop the entry, next reader waits for fresh data
revalidateTag('posts', { expire: 0 });

Why: The single-argument form still runs if the TypeScript error is suppressed, but the vendor documents that behavior as deprecated and subject to removal. Choosing explicitly also forces the decision that the old call hid: whether a reader may be served stale data after a mutation.

Server Actions

Projects SHOULD use Server Actions for mutations. Every Server Action MUST authenticate the caller, MUST authorize the specific operation, MUST validate its input, and MUST return only the data the client needs.

Middleware

Projects SHOULD use middleware for cross-cutting concerns:

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Authentication redirect
  const token = request.cookies.get('auth-token');

  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  // Add custom headers
  const response = NextResponse.next();
  response.headers.set('x-custom-header', 'value');

  return response;
}

// Specify which routes to run middleware on
export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*'],
};

Rate Limiting

Projects SHOULD use Upstash Ratelimit⁹ for serverless-compatible rate limiting:

Edge Middleware Implementation

NextRequest.ip was removed in Next.js 15. Limiters MUST key on a verified identity where one exists, and otherwise on a client address supplied by the hosting platform. They MUST NOT read a client-supplied x-forwarded-for header directly unless every proxy in front of the application is known to overwrite it, and MUST NOT collapse unidentifiable callers into a single shared bucket.

Don’t — request.ip no longer exists (TS2339), the header fallback is attacker-controlled on an untrusted chain, and every unknown client shares one 127.0.0.1 bucket:

const ip = request.ip ?? request.headers.get('x-forwarded-for') ?? '127.0.0.1';
const { success } = await ratelimit.limit(ip);

npm install @upstash/ratelimit@2.0.8 @upstash/redis@1.38.4 @vercel/functions@3.9.5

// middleware.ts
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';
import { ipAddress } from '@vercel/functions';
import { NextRequest, NextResponse } from 'next/server';
import { getVerifiedSubject } from '@/lib/auth-utils';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '10 s'), // 10 requests per 10 seconds
  analytics: true,
  prefix: '@upstash/ratelimit',
});

async function identify(request: NextRequest): Promise<string | null> {
  // Authenticated callers are limited per account, not per network address:
  // one office NAT must not share a bucket with unrelated users.
  const subject = await getVerifiedSubject(request);
  if (subject) {
    return `user:${subject}`;
  }

  // Anonymous callers: the platform's client address, never a raw header.
  const ip = ipAddress(request);
  return ip ? `ip:${ip}` : null;
}

export async function middleware(request: NextRequest) {
  const identifier = await identify(request);

  if (identifier === null) {
    // No trustworthy identity: reject rather than share one global bucket.
    return NextResponse.json({ error: 'Too many requests' }, { status: 429 });
  }

  const { success, limit, reset, remaining } = await ratelimit.limit(
    identifier,
    {
      ip: ipAddress(request),
      userAgent: request.headers.get('user-agent') ?? undefined,
      country: request.headers.get('x-vercel-ip-country') ?? undefined,
    }
  );

  if (!success) {
    return NextResponse.json(
      { error: 'Too many requests' },
      {
        status: 429,
        headers: {
          'X-RateLimit-Limit': limit.toString(),
          'X-RateLimit-Remaining': remaining.toString(),
          'X-RateLimit-Reset': reset.toString(),
        },
      }
    );
  }

  const response = NextResponse.next();
  response.headers.set('X-RateLimit-Limit', limit.toString());
  response.headers.set('X-RateLimit-Remaining', remaining.toString());
  return response;
}

export const config = {
  matcher: '/api/:path*',
};

Why: ipAddress() reads x-real-ip, which the Vercel edge network sets on every inbound request; the platform, not the client, controls its value. Projects on other hosts MUST substitute that host’s equivalent helper and MUST confirm the edge overwrites rather than appends the forwarding header — an appended value is caller-controlled and lets one attacker mint an unlimited number of buckets. Keying authenticated traffic on the account identifier also keeps a shared corporate address from throttling legitimate users.

Multi-Region Configuration

Projects with global users SHOULD use regional Redis instances:

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(100, '60 s'),
  // Automatically routes to nearest region
  enableProtection: true,
});

With enableProtection enabled, callers MUST pass the request metadata shown above (ip, userAgent, country) to limit(). Upstash’s deny lists match on those fields, and an omitted field cannot be matched.

Why: Edge middleware blocks traffic before it reaches your backend, reducing costs and protecting against abuse. Multi-region Redis minimizes latency globally.

API Routes (Route Handlers)

Projects MAY use Route Handlers for API endpoints. A Route Handler is a public endpoint: it MUST authenticate the caller, MUST authorize the specific resource and operation, MUST validate its body, and MUST return a projection rather than a whole database row.

// app/api/users/route.ts
import { NextResponse } from 'next/server';
import { db } from '@/lib/db';
import { getCurrentUser } from '@/lib/auth-utils';
import { z } from 'zod';

const createUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.email(),
});

// Return only fields the caller is allowed to see
const publicUser = (user: { id: string; name: string; email: string }) => ({
  id: user.id,
  name: user.name,
  email: user.email,
});

export async function GET() {
  const actor = await getCurrentUser();
  if (!actor) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  if (!actor.permissions.includes('user:list')) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  const users = await db.users.findMany();
  return NextResponse.json(users.map(publicUser));
}

export async function POST(request: Request) {
  const actor = await getCurrentUser();
  if (!actor) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  if (!actor.permissions.includes('user:create')) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  const parsed = createUserSchema.safeParse(await request.json());
  if (!parsed.success) {
    return NextResponse.json({ error: 'Invalid body' }, { status: 400 });
  }

  // Role is assigned by the server; it is never read from the request
  const user = await db.users.create({
    data: { ...parsed.data, role: 'user' },
  });
  return NextResponse.json(publicUser(user), { status: 201 });
}

Don’t — an anonymous caller can create a user, and the raw body reaches the database, so any extra field (role: 'admin') is written verbatim:

export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.users.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

// app/api/users/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;

  const actor = await getCurrentUser();
  if (!actor) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  // Resource-level check: reading yourself differs from reading anyone
  if (actor.id !== id && !actor.permissions.includes('user:read')) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  const user = await db.users.findUnique({ where: { id } });

  if (!user) {
    return NextResponse.json({ error: 'User not found' }, { status: 404 });
  }

  return NextResponse.json(publicUser(user));
}

export async function DELETE(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;

  const actor = await getCurrentUser();
  if (!actor) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  if (!actor.permissions.includes('user:delete')) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  await db.users.delete({ where: { id } });
  return new NextResponse(null, { status: 204 });
}

Why: Route Handlers provide REST API endpoints when needed. For form submissions and mutations, prefer Server Actions for better type safety and progressive enhancement.

Why these checks: An authorization check performed in a page, a layout, or middleware protects only that render path. DELETE /api/users/:id is reachable directly with curl, so the identity and permission checks MUST live in the handler body. Returning db.users.findUnique(...) verbatim also leaks every column added to the table later — including password hashes and tokens — which is why the handler returns an explicit projection.

Route Handler params is a promise. A synchronous { params: { id: string } } context type fails next build with TS2344.

Unit and Integration Tests

Projects MUST test Server and Client Components separately:

// components/counter.test.tsx
import { render, screen, fireEvent } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import Counter from './counter';

describe('Counter', () => {
  it('increments count on click', () => {
    render(<Counter />);
    const button = screen.getByRole('button');

    expect(button).toHaveTextContent('Count: 0');
    fireEvent.click(button);
    expect(button).toHaveTextContent('Count: 1');
  });
});

// components/user-profile.test.tsx
import { render, screen } from '@testing-library/react';
import { describe, it, expect, vi } from 'vitest';
import UserProfile from './user-profile';

vi.mock('@/lib/db', () => ({
  getUser: vi.fn().mockResolvedValue({
    name: 'John Doe',
    email: 'john@example.com',
  }),
}));

describe('UserProfile', () => {
  it('renders user data', async () => {
    render(await UserProfile({ userId: '1' }));
    expect(screen.getByText('John Doe')).toBeInTheDocument();
    expect(screen.getByText('john@example.com')).toBeInTheDocument();
  });
});

E2E Tests

Projects SHOULD use Playwright for end-to-end testing:

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Authentication', () => {
  test('user can log in', async ({ page }) => {
    await page.goto('/login');

    await page.fill('input[name="email"]', 'test@example.com');
    await page.fill('input[name="password"]', 'password123');
    await page.click('button[type="submit"]');

    await expect(page).toHaveURL('/dashboard');
    await expect(page.locator('h1')).toContainText('Dashboard');
  });

  test('protected route redirects to login', async ({ page }) => {
    await page.goto('/dashboard');
    await expect(page).toHaveURL('/login');
  });
});

Why: Vitest provides fast unit testing with React Server Component support. Playwright enables reliable E2E testing across browsers with automatic waiting and screenshot/video recording.

Authentication

New projects SHOULD use Better Auth¹⁰. Projects with a working Auth.js¹¹ deployment MAY stay on it; Auth.js v5 remains a prerelease and MUST be pinned to a tested version.

Auth.js (Existing Projects)

npm install next-auth@5.0.0-beta.32

@auth/core MUST NOT be installed at a version other than the one next-auth depends on (5.0.0-beta.32 pins @auth/core@0.41.3). A second copy at a different version splits the shared interfaces and silently breaks the type augmentation below.

// auth.ts
import NextAuth from 'next-auth';
import GitHub from 'next-auth/providers/github';
import Google from 'next-auth/providers/google';
import Credentials from 'next-auth/providers/credentials';
import { PrismaAdapter } from '@auth/prisma-adapter';
import { prisma } from '@/lib/db';

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    GitHub, // Uses AUTH_GITHUB_ID and AUTH_GITHUB_SECRET automatically
    Google,
    Credentials({
      credentials: {
        email: { label: 'Email', type: 'email' },
        password: { label: 'Password', type: 'password' },
      },
      async authorize(credentials) {
        // Validate credentials against database
        const user = await validateUser(credentials);
        return user ?? null;
      },
    }),
  ],
  session: { strategy: 'jwt' }, // Required for Edge Runtime/middleware
  callbacks: {
    authorized({ auth, request }) {
      const isLoggedIn = !!auth?.user;
      const isProtected = request.nextUrl.pathname.startsWith('/dashboard');
      if (isProtected && !isLoggedIn) return false;
      return true;
    },
    jwt({ token, user }) {
      if (user) {
        token.role = user.role;
      }
      return token;
    },
    session({ session, token }) {
      session.user.role = token.role;
      return session;
    },
  },
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/auth';
export const { GET, POST } = handlers;

Type Augmentation for Custom Fields

Auth.js types custom session and token fields through module augmentation. Projects that add a field such as role MUST declare it, and MUST include the declaration file in tsconfig.json.

Don’t — user.role and session.user.role fail with TS2339: Property 'role' does not exist, and token.role is typed unknown because JWT only carries an index signature:

jwt({ token, user }) {
  if (user) {
    token.role = user.role;
  }
  return token;
},

Do:

// types/next-auth.d.ts
import type { DefaultSession } from 'next-auth';
import type { Role } from '@/lib/roles';

declare module 'next-auth' {
  interface User {
    role: Role;
  }

  interface Session {
    user: { role: Role } & DefaultSession['user'];
  }
}

// The JWT interface is declared in @auth/core/jwt; next-auth only re-exports it
declare module '@auth/core/jwt' {
  interface JWT {
    role: Role;
  }
}

export {};

Augmenting next-auth/jwt MUST NOT be used: that module is a bare export * from '@auth/core/jwt', so a declare module 'next-auth/jwt' block creates a new interface instead of merging into the original. JWT keeps its Record<string, unknown> index signature, token.role stays unknown, and the session callback fails with TS2322: Type 'unknown' is not assignable to type '"user" | "moderator" | "admin"'.

// tsconfig.json
{
  "include": ["next-env.d.ts", "types/**/*.d.ts", "**/*.ts", "**/*.tsx"]
}

The database model MUST supply the same field, or the adapter returns a User without role and the augmentation is a lie:

// prisma/schema.prisma
model User {
  id    String @id @default(cuid())
  email String @unique
  role  String @default("user")
}

Session Strategies

Strategy	Pros	Cons
JWT	Edge-compatible, no DB lookups, horizontal scaling	Cannot revoke until expiry
Database	Immediate revocation, audit trail	Requires DB access, more latency

Projects MUST use JWT strategy when using middleware auth checks (Edge Runtime cannot access databases directly).

Why: Better Auth and Auth.js both provide type-safe authentication with zero vendor lock-in. JWT sessions work in Edge Runtime while database sessions enable immediate session revocation for security-critical applications.

Vercel (Recommended)

Projects deployed to Vercel¹² SHOULD use automatic deployments:

# Install Vercel CLI
npm i -g vercel

# Deploy to production
vercel --prod

# Preview deployments happen automatically on git push

// next.config.ts
import type { NextConfig } from 'next';

const config: NextConfig = {
  // Vercel-specific optimizations are automatic
  images: {
    // AVIF omitted deliberately - see Image Format Security
    formats: ['image/webp'],
  },
};

export default config;

Why: Vercel provides zero-config deployments, automatic HTTPS, edge functions, and built-in analytics. Preview deployments for every pull request enable safe testing before production.

Self-Hosted

Projects self-hosting MUST use the standalone output:

// next.config.ts
const config: NextConfig = {
  output: 'standalone',
};

# Dockerfile
# node:20-alpine; registry manifest digest.
FROM node@sha256:fb4cd12c85ee03686f6af5362a0b0d56d50c58a04632e6c0fb8363f609372293 AS base

# Dependencies
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Builder
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Runner
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

CMD ["node", "server.js"]

# docker-compose.yml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
    depends_on:
      - db

  db:
    # postgres:17; registry manifest digest.
    image: postgres@sha256:2d2b8998d31037bf721cfdf764d76ba74171b4fab3431b7f72c27c56ddbdf9e3
    environment:
      POSTGRES_PASSWORD: pass
      POSTGRES_USER: user
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Why: Standalone output creates a minimal Node.js server with only required dependencies. Docker enables consistent deployments across environments with isolated dependencies.

Turbopack

Projects SHOULD use Turbopack for faster development builds:

// package.json
{
  "scripts": {
    "dev": "next dev --turbo",
    "build": "next build"
  }
}

Why: Turbopack provides 700x faster updates than Webpack in development. Production builds still use Webpack for maximum optimization.

Image Optimization

Projects MUST use Next.js Image component:

import Image from 'next/image';

// Local images (imported)
import heroImage from '@/public/hero.jpg';

export function Hero() {
  return (
    <Image
      src={heroImage}
      alt="Hero image"
      priority // LCP optimization
      placeholder="blur" // Automatic blur placeholder
    />
  );
}

// Remote images
export function Avatar({ src }: { src: string }) {
  return (
    <Image
      src={src}
      alt="User avatar"
      width={40}
      height={40}
      // Remote images require dimensions
    />
  );
}

// next.config.ts
const config: NextConfig = {
  images: {
    // AVIF omitted deliberately - see Image Format Security below
    formats: ['image/webp'],
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
        pathname: '/images/**',
      },
    ],
  },
};

Why: Next.js Image automatically optimizes images, serves modern formats (WebP), generates responsive sizes, and lazy loads by default. remotePatterns is scoped to a single host and path prefix so the optimizer cannot be pointed at arbitrary URLs.

Image Format Security

Projects MUST run Next.js 16.3.3 or later on the 16.x line, or 15.5.24 or later on the 15.x line. Projects MUST NOT list image/avif in images.formats until a Next.js release re-enables AVIF optimization with the fixed upstream libheif.

Why: The August 2026 security release¹ documents an unauthenticated remote code execution (GHSA-2xp9-vwfh-vxw4 / GHSA-g89c-p67h-r497): a flaw in the libheif library used by sharp is reachable whenever Next.js optimizes an attacker-controlled AVIF image. Any remote image the optimizer accepts is attacker-controlled input.

Removing image/avif from formats is not a substitute for the patch. formats governs the output format the optimizer prefers, not the input formats it will decode; only the patched releases disable AVIF optimization. Upgrade first, then treat the format list as defense in depth.

// package.json - pin at or above the patched release
{
  "dependencies": {
    "next": "16.3.4"
  }
}

Font Optimization

Projects SHOULD use next/font for automatic font optimization:

// app/layout.tsx
import { Inter, Roboto_Mono } from 'next/font/google';

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
});

const robotoMono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-roboto-mono',
});

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
      <body>{children}</body>
    </html>
  );
}

/* app/globals.css */
body {
  font-family: var(--font-inter), sans-serif;
}

code {
  font-family: var(--font-roboto-mono), monospace;
}

Why: next/font automatically self-hosts Google Fonts (eliminating external requests), optimizes loading with CSS size-adjust, and prevents layout shift.

Metadata and SEO

Projects MUST define metadata for SEO:

// app/layout.tsx
import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: {
    template: '%s | My App',
    default: 'My App',
  },
  description: 'My awesome Next.js app',
  openGraph: {
    title: 'My App',
    description: 'My awesome Next.js app',
    images: ['/og-image.jpg'],
  },
};

// app/blog/[slug]/page.tsx
import type { Metadata } from 'next';

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  };
}

Why: Next.js automatically generates SEO tags from metadata, supports dynamic per-page metadata, and provides type safety for Open Graph and Twitter Cards.

Real-Time Communication

Serverless platforms like Vercel MUST NOT use WebSockets directly (serverless functions are ephemeral and cannot maintain persistent connections). Projects SHOULD use managed real-time services:

Self-Hosted Alternative

For self-hosted deployments with persistent servers, Socket.IO¹⁵ MAY be used:

// server.ts (custom server, NOT compatible with Vercel)
import { createServer } from 'http';
import { Server } from 'socket.io';
import next from 'next';

const dev = process.env.NODE_ENV !== 'production';
const app = next({ dev });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  const server = createServer((req, res) => {
    handle(req, res);
  });

  const io = new Server(server);

  io.on('connection', (socket) => {
    socket.on('message', (data) => {
      io.emit('message', data);
    });
  });

  server.listen(3000);
});

Why: Managed services handle WebSocket infrastructure, scaling, and global presence. They integrate cleanly with serverless functions while providing reliable real-time delivery.

Background Jobs

Projects running on serverless platforms SHOULD use managed background job services:

Circuit Breakers

Projects calling external APIs SHOULD implement circuit breakers with Opossum²⁰:

Feature Flags

Projects SHOULD use the Vercel Flags SDK²¹ for feature flag integration:

Static Site Generation (SSG) and ISR

This section describes the route-segment caching model, the model that applies when cacheComponents is not enabled. It remains supported in Next.js 16. Projects that have enabled Cache Components MUST NOT mix the two: use use cache, cacheLife, and cacheTag instead of the dynamic, revalidate, and dynamicParams segment exports.

Projects SHOULD use Static Site Generation (SSG) and Incremental Static Regeneration (ISR) for content that doesn’t change frequently.

Internationalization (i18n)

Projects with multilingual content SHOULD implement i18n using Next.js routing patterns and message catalogs.

Locale Configuration

One module MUST own the supported locale list, and every other file MUST import it. Duplicated lists drift, and a locale that exists in the middleware but not in the dictionary map becomes a runtime crash.

// lib/i18n-config.ts
export const LOCALES = ['en', 'fr', 'de', 'es'] as const;

export type Locale = (typeof LOCALES)[number];

export const DEFAULT_LOCALE: Locale = 'en';

export function isLocale(value: string): value is Locale {
  return (LOCALES as readonly string[]).includes(value);
}

Using Dictionaries in Components

The [lang] segment is an arbitrary URL string. Pages MUST validate it at runtime before using it as a dictionary key, and SHOULD set dynamicParams = false when only the generated locales are valid.

// app/[lang]/page.tsx
import { notFound } from 'next/navigation';
import { getDictionary } from '@/lib/dictionaries';
import { isLocale, LOCALES } from '@/lib/i18n-config';

// Route-segment model only: anything outside generateStaticParams is a 404.
// Omit this line when cacheComponents is enabled - the two are incompatible.
export const dynamicParams = false;

export default async function Home({
  params,
}: {
  params: Promise<{ lang: string }>;
}) {
  const { lang } = await params;

  if (!isLocale(lang)) {
    notFound();
  }

  const dict = await getDictionary(lang);

  return (
    <main>
      <h1>{dict.home.title}</h1>
      <p>{dict.home.description}</p>
    </main>
  );
}

export function generateStaticParams() {
  return LOCALES.map((lang) => ({ lang }));
}

Don’t — the annotation is erased at build time, so an unsupported segment reaches the lookup and throws TypeError: dictionaries[locale] is not a function, producing a 500 instead of a 404:

export default async function Home({
  params,
}: {
  params: Promise<{ lang: Locale }>;
}) {
  const { lang } = await params;
  const dict = await getDictionary(lang);
  // ...
}

Why: The language-detection middleware redirects unprefixed paths, but it does not police the segment. Its own matcher excludes /api, /_next/*, and favicon.ico, so a request such as /api-docs is never rewritten and still matches app/[lang]/page.tsx with lang = 'api-docs'. Without the guard, Next.js 16.3.4 returns HTTP 500 with TypeError: dictionaries[locale] is not a function; with it, the same request returns 404. Never rely on a TypeScript annotation to constrain a value that arrives from a URL.

Applications needing message extraction, pluralization, ICU formatting, or typed navigation helpers SHOULD use next-intl²⁴ instead of extending this hand-rolled catalog.