turbopackLocalPostcssConfig

Core Idea

Muda a ordem em que o Turbopack resolve postcss.config.js: por default, um config na raiz do projeto sempre prevalece sobre configs em subdiretórios; habilitando essa opção, o config mais próximo do arquivo CSS (na própria pasta) passa a ter precedência, com o config da raiz servindo só como fallback.

Key Concepts

• turbopackLocalPostcssConfig: boolean, default false. Só relevante usando Turbopack (next dev ou next build com --turbopack).
• Ordem default (false): Project root → CSS file's directory (root config vence).
• Ordem invertida (true): CSS file's directory → project root (config local vence, root é fallback).

Code Examples

const nextConfig: NextConfig = {
  experimental: {
    turbopackLocalPostcssConfig: true,
  },
}

• O que demonstra: habilita resolução per-directory de PostCSS config, útil em monorepo com múltiplos apps/design system packages.

my-app/
├── postcss.config.js          ← fallback (applied if no local config is found)
├── app/
│   └── page.module.css        ← uses root config
└── packages/
    └── ui/
        ├── postcss.config.js  ← takes precedence for files in this directory
        └── button.module.css  ← uses packages/ui/postcss.config.js

• O que demonstra: layout de monorepo onde packages/ui tem transforms PostCSS diferentes do app principal, e turbopackLocalPostcssConfig: true faz isso funcionar.

Reference Tables

Setting	Config resolution order
false (default)	Project root → CSS file's directory
true	CSS file's directory → project root

Version	Changes
v16.3.0	turbopackLocalPostcssConfig introduced.

Key Takeaways

1. Sem essa flag, um postcss.config.js na raiz "vence" mesmo se houver config específico em subpasta.
2. Útil especificamente para monorepos com múltiplos apps ou pacotes de design system que precisam de transforms PostCSS diferentes.
3. Só afeta resolução via Turbopack; não muda comportamento no webpack.

Connects To

• turbopack: opção-pai de customização geral do Turbopack.