turbopackChunking

experimental.turbopackChunking lets you configure Turbopack's production JavaScript chunker. These options allow you to change the assumptions the chunker makes about user behavior and tweak the raw size thresholds it uses.

By default, Turbopack's chunking is configured as follows:

import type { NextConfig } from 'next'
 
const nextConfig = {
  experimental: {
    turbopackChunking: {
      minChunkSize: 50000,
      maxChunkCountPerGroup: 40,
      maxMergeChunkSize: 200000,
    },
  },
} satisfies NextConfig
 
export default nextConfig

Size Thresholds

The following options control how aggressively Turbopack merges chunks and how large a chunk is allowed to grow. Sizes are in bytes of uncompressed, unminified code (roughly 5x the size of the compressed, minified output).

• minChunkSize (default 50000): Turbopack will avoid creating more than one chunk smaller than this size by merging small chunks into larger ones. Raising this number will produce fewer, larger chunks. Meanwhile, lowering it will produce more chunks that are smaller.
• maxChunkCountPerGroup (default 40): Turbopack will not emit more than this many chunks per chunk group (eg. a route or a dynamic import). Lowering this number will lead to more aggressive merging and less network requests per-page. Raising it will produce smaller chunks and increase the likelihood of cache hits when navigating.
• maxMergeChunkSize (default 200000): Turbopack never merges a chunk larger than this size with other chunks. This keeps the code in large chunks from being duplicated across multiple large output chunks.

When merging chunks, the trade-off being made is an improvement to performance on initial page loads at the cost of navigation performance. This is because each additional network request being made is costly, however, smaller chunks are more likely to be re-usable across pages.

Heuristics

These change the assumptions the chunker makes when weighing whether merging two chunks is worth it.

• clusters (an array of arrays of RegExp, e.g. [[/^\/dashboard/, /^\/settings/]]): groups of routes that are commonly visited together, matched against the route pathname. Turbopack assumes navigations are likely to stay within a cluster, so chunks shared by a cluster's routes are merged more eagerly.
• firstPageLoadPriority (a number between 0 and 1): how heavily to weight the benefit of merging chunks for a single page load. Higher values merge more eagerly. If you don't have a better value, your site's bounce rate is a good approximation.
• priorityRoutes (an array of RegExp): routes that are often the first page a visitor lands on (e.g. the homepage). Their client-side bundles are merged more eagerly to reduce the single-route request cost, at the cost of extra requests when navigating to other pages.
• priorityBoost (default 1.5): a multiplier on the single-request probability of priorityRoutes routes. Higher values merge those routes' bundles more aggressively.
• requestCost (default 200000): the estimated cost of an additional request, in bytes of uncompressed, unminified code. Larger values bias toward fewer, larger chunks and fewer requests overall.