cssChunking

Core Idea

experimental.cssChunking controls how Next.js splits and reorders CSS files into chunks so a route loads closer to only the CSS it needs — tune it when you see excess unused CSS or ordering bugs.

Key Concepts

• true (default, webpack+Turbopack): merges CSS files when possible, inferring dependencies from import order to reduce chunk/request count.
• false (webpack only): no merging/reordering; each import stays as-is.
• 'strict' (webpack only): loads CSS in exact import order — more chunks/requests, but avoids ordering bugs between files with implicit dependencies.
• 'graph' (Turbopack only): cost-based graph algorithm that groups CSS across routes, balancing bytes vs. requests via requestCost and weightDistribution.
• requestCost (default 20000): estimated byte cost of one extra CSS request; higher = fewer, larger merged chunks.
• weightDistribution (default 0.1): how a shared chunk's cost is distributed across routes weighted by how much CSS each imports; 0 = every route weighted equally, higher = routes with less CSS protected more.

Code Examples

import type { NextConfig } from 'next'

const nextConfig = {
  experimental: {
    cssChunking: 'graph',
  },
} satisfies NextConfig

export default nextConfig

• O que demonstra: ativar a estratégia graph (só Turbopack).

const nextConfig = {
  experimental: {
    cssChunking: {
      type: 'graph',
      requestCost: 100000,
      weightDistribution: 0.1,
    },
  },
} satisfies NextConfig

• O que demonstra: ajustar finamente requestCost/weightDistribution do modo graph.

Reference Tables

Valor	Bundler	Comportamento
true (default)	webpack e Turbopack	mescla CSS pra reduzir chunks/requests
false	webpack apenas	não mescla nem reordena
'strict'	webpack apenas	carrega na ordem exata de import
'graph'	Turbopack apenas	agrupamento por grafo de custo

Anti-patterns

• Trocar de estratégia sem motivo: para a maioria dos apps o default (true) já é a escolha certa em ambos bundlers.
• Ignorar CSS não usado por interação: Chrome DevTools Coverage conta :hover/:focus/classes toggladas via JS como "não usadas" até serem disparadas — não tire conclusões precipitadas do relatório.

Key Takeaways

1. Em Turbopack, mude pra graph por performance (reduzir CSS não usado por rota); em webpack, mude pra 'strict' por correção (bugs de ordem de import).
2. requestCost decide o ponto de corte entre mesclar (menos requests) e separar (menos bytes não usados).
3. CSS Modules ajudam a evitar CSS morto naturalmente, escopando estilos ao componente que os importa.
4. Feature ainda experimental, não recomendada para produção sem avaliação.

Connects To

• CSS Modules: técnica recomendada pra reduzir CSS não usado antes de mexer em cssChunking.