What's new in Next.js 16

Next.js 16 is a monumental release, marking a significant step forward in stability, performance, and developer control. This isn't just another incremental update; it's a carefully orchestrated refinement of features that have been rigorously tested and proven over the past year. Get ready to dive into async route parameters, Turbopack as the default, and a streamlined development experience!

What's New in Next.js 16: A Deep Dive

Next.js 16 is here, and it’s the kind of release where the team finally stabilizes everything they’ve been testing for the past year. Experimental features are graduating to stable, deprecated APIs are getting removed, and the whole framework is getting faster. If you're planning to upgrade, you'll want to know what changed and why it matters. Let's break down the key updates.

Route Parameters Are Now Asynchronous

This is the biggest change you'll encounter. Route parameters, previously synchronous, are now asynchronous, significantly impacting how you access and use them across your application.

The Impact:

Every component that previously accessed route parameters (using params or searchParams) now requires you to await them. This applies to:

• Pages
• Layouts
• Route handlers
• Image generation functions (e.g., opengraph-image, twitter-image, icon, apple-icon)

Code Examples:

Next.js 15 (Synchronous):

// Next.js 15 - synchronous params
export default function Page({ params }) {
  const { slug } = params;
  return <p>Slug: {slug}</p>;
}

Next.js 16 (Asynchronous):

// Next.js 16 - asynchronous params
export default async function Page({ params }) {
  const { slug } = await params.slug;
  return <p>Slug: {slug}</p>;
}

Image Generation Example:

// Next.js 16 - image generation
export async function generateImageMetadata({ params }) {
  const { slug } = await params;
  return [{ id: '1' }, { id: '2' }];
}

export default async function Image({ params, id }) {
  const { slug } = await params;
  const imageId = await id; // id is now Promise<string>
  return <p>Image ID: {imageId} and Slug: {slug}</p>;
}

Why Asynchronous Parameters?

The shift to asynchronous parameters is driven by the need for streaming and concurrent rendering. When parameters are synchronous, Next.js blocks, awaiting all resolutions before rendering can begin. Making them async enables the framework to initiate page shell streaming while parameters are resolved in the background.

This change is especially beneficial when parameter resolution involves database validation, edge configuration resolution, or network requests. Async patterns give Next.js the space to optimize these processes without hindering the entire render pipeline.

TypeScript Implications:

TypeScript users should prepare for type updates. Params = { slug: string } transitions to Params = Promise<{ slug: string }>. This change propagates throughout the application, impacting numerous files.

Handling in Client Components:

In client components, React's use hook helps unwrap the promise:

'use client'
import { use } from 'react'

export default function ClientPage(props: { params: Promise<{ slug: string }> }) {
  const params = use(props.params)
  const slug = params.slug;
  return <p>Slug: {slug}</p>;
}

Codemod and Manual Fixes:

The automated codemod handles much of the conversion, but it isn't foolproof. Complex destructuring, parameters passed through multiple functions, or those used in helper functions may require manual intervention. The codemod leaves @next-codemod-error comments to highlight areas requiring review.

Turbopack Becomes the Default Bundler

Turbopack, Vercel's bundler written in Rust, is now the default in Next.js 16. This transition simplifies the development process and unlocks substantial performance gains.

Transitioning to Turbopack:

Migrating is straightforward. Simply remove the --turbopack flag from your package.json scripts. For instance, change "dev": "next dev --turbopack" to "dev": "next dev".

Performance Benefits:

Turbopack offers noticeable performance improvements, particularly for larger applications. Cold starts are faster, hot module replacement is nearly instantaneous, and production builds are accelerated, scaling with the number of modules.

Configuration Changes:

Turbopack configurations have been moved out of the experimental section:

Next.js 15 (Experimental):

const nextConfig = {
  experimental: {
    turbopack: {
      // options
    },
  },
}

Next.js 16 (Stable):

const nextConfig = {
  turbopack: {
    // options
  },
}

Filesystem Caching:

A new filesystem caching feature can be enabled using experimental.turbopackFileSystemCacheForDev or experimental.turbopackFileSystemCacheForBuild. This feature saves compilation artifacts in .next between runs, significantly speeding up restarts and rebuilds.

const nextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true,
    turbopackFileSystemCacheForBuild: true,
  },
}

Webpack Opt-Out:

If Webpack is required for specific tasks, you can opt-out by adding --webpack to your build command: "build": "next build --webpack". This will revert the production build back to Webpack, while development still uses Turbopack.

Addressing Legacy Webpack Patterns:

Legacy Webpack patterns, such as Sass imports using the tilde prefix (~), may need adjustments. Turbopack does not support this out-of-the-box, but you can establish a resolve alias:

const nextConfig = {
  turbopack: {
    resolveAlias: {
      '~*': '*',
    },
  },
}

Similarly, for client code that accidentally imports Node modules (like fs), you can set up fallbacks using resolveAlias to avoid build errors.

React Compiler Support

Next.js 16 embraces the React Compiler (which will be stable in React 19) to automatically memoize components, reducing unnecessary re-renders. This minimizes the need for manual useCallback and useMemo implementations.

Enabling the React Compiler:

const nextConfig = {
  reactCompiler: true,
}

Improved Caching APIs

Next.js 16 stabilizes caching APIs, providing greater control over cache behavior. The previously prefixed unstable_ APIs are now production-ready.

Key Changes:

• cacheLife: Sets precise cache durations directly in code.
• cacheTag: Implements a tagging system for targeted cache invalidation.
• updateTag: Addresses "read-your-writes" issues by expiring and refreshing cache in the same request.
• refresh: Triggers client-side router refreshes from server actions.

Code Examples:

'use server'
import { updateTag } from 'next/cache'

export async function updateUserProfile(userId: string, profile: Profile) {
  await db.users.update(userId, profile)
  // Expire cache and refresh immediately - user sees changes right away
  updateTag(`user-${userId}`)
}

'use server'
import { refresh } from 'next/cache'

export async function markNotificationAsRead(notificationId: string) {
  await db.notifications.markAsRead(notificationId)
  // Refresh the notification count displayed in the header
  refresh()
}

Imports:

// Next.js 15 - experimental with aliasing
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

// Next.js 16 - stable, clean imports
import { cacheLife, cacheTag, updateTag, refresh } from 'next/cache'

cacheComponents (formerly experimental.dynamicIO):

This feature, linked to Partial Pre-Rendering (PPR), has also been stabilized and renamed:

// Next.js 15
const nextConfig = {
  experimental: {
    dynamicIO: true,
  },
}

// Next.js 16
const nextConfig = {
  cacheComponents: true,
}

Middleware Renamed to Proxy

"Middleware" is now "Proxy" to avoid confusion with other frameworks.

Migration:

1. Rename the file: mv middleware.ts proxy.ts
2. Update the export:

// Next.js 15
export function middleware(request: Request) {}

// Next.js 16
export function proxy(request: Request) {}

Important Change: Proxy functions now run exclusively on the Node.js runtime, removing Edge runtime support.

Addressing the Loss of Edge Runtime:

If you relied on Edge middleware for geolocation routing, A/B testing, or auth checks, consider adapting your logic for Node.js. Alternatively, move latency-sensitive logic to external Edge functions like Vercel Edge Functions or Cloudflare Workers.

Proxy Function Limitations:

Proxy functions can no longer return response bodies. They are now strictly for request modification, rewriting, and redirection. Custom responses should be handled in route handlers or API routes.

Example: Authentication Proxy:

// Old pattern - no longer supported
export function middleware(request: Request) {
  if (!isAuthValid(request)) {
    return NextResponse.json({ message: 'Auth required' }, { status: 401 })
  }
  return NextResponse.next()
}

// New pattern - redirect instead
export function proxy(request: Request) {
  if (!isAuthValid(request)) {
    const loginUrl = new URL('/login', request.url)
    loginUrl.searchParams.set('from', request.nextUrl.pathname)
    return NextResponse.redirect(loginUrl)
  }
  return NextResponse.next()
}

AMP Support Removed

AMP support is no longer available in Next.js.

Image Optimization Changes

Next.js 16 introduces tighter security and performance enhancements to image handling.

Key Changes:

• Local Images with Query Strings: Now require explicit configuration via localPatterns.

  const nextConfig = {
    images: {
      localPatterns: [
        {
          pathname: '/assets/**',
          search: '?v=1',
        },
      ],
    },
  }
  

• Default Minimum Cache TTL: Increased from 60 seconds to 4 hours (14400 seconds). You can override this with the minimumCacheTTL property in your next config.

• Image Quality Defaults: The default quality level is now a single value ([75]). Multiple quality levels are supported using the qualities property in your next config.

• Image Sizes: Dropped 16px from the default imageSizes array.

• Remote Images: images.domains is deprecated. Use images.remotePatterns with explicit protocol definition.

  // Secure
  const nextConfig = {
    images: {
      remotePatterns: [
        {
          protocol: 'https',
          hostname: 'example.com',
        },
      ],
    },
  }
  

• images.maximumRedirects: Limits HTTP redirects to 3 (previously unlimited).

• images.dangerouslyAllowLocalIP: Allows image optimization for local IPs (use with caution).

Runtime Configuration Replaced with Environment Variables

serverRuntimeConfig and publicRuntimeConfig are removed in favor of environment variables.

.env
NEXT_PUBLIC_API_URL="/api"  # Client-side
DATABASE_URL="postgres://..." # Server-side only

ESLint Integration Changes

The next lint command is removed. Use ESLint directly.

npx @next/codemod@canary next-lint-to-eslint-cli .

Migration Strategy

Upgrading to Next.js 16 requires careful planning and systematic testing.

1. Run the Codemod:

   npx @next/codemod@canary upgrade latest
   

2. Manual Fixes: Address any @next-codemod-error comments left by the codemod. Common issues include:

   • Parameters passed through helper functions.
   • Complex destructuring patterns.
   • Components exported/imported across files without type information.

3. Systematic Testing:

   • Route Handlers: Test dynamic segments (segmentData.params).
   • Page Components: Dynamic routes and search parameters.
   • Layout Components: Parameter access.
   • Image Handling: Ensure query string configurations are correctly set with localPatterns, and remote image domains are migrated to remotePatterns. Check minimumCacheTTL.
   • Middleware: Verify logic operates correctly on the Node.js runtime, and refactor middleware that returned response bodies to use redirects/rewrites.
   • Environment Variables: Ensure correct configuration, using NEXT_PUBLIC_ prefix for client-side variables.
   • TypeScript: Address type changes ({ slug: string } -> Promise<{ slug: string }>). Run tsc --noEmit to check.

4. Parallel Routes: Empty slots now require default.js files.

5. Scroll Behavior: If needed, add data-scroll-behavior="smooth" to your root HTML.

6. CI/CD Pipelines: Adjust caching configurations for .next directory structure changes.

7. Build Adapters: Explore experimental.adapterPath for custom deployment targets.

8. Error Monitoring: Set up error monitoring to capture full async stack traces.

Next.js 16 represents a significant evolution, offering improved performance, enhanced developer control, and a more streamlined development experience. By carefully reviewing the changes and following the migration strategy outlined above, you can successfully upgrade your projects and unlock the benefits of this powerful release.