Capítulo 260 de 456

useLightningcss

Core Idea

Habilita suporte experimental ao Lightning CSS (transformer/minifier de CSS em Rust, rápido) no pipeline webpack. No Turbopack, Lightning CSS já é o processador de CSS padrão desde o Next 14.2, e essa opção não tem efeito lá.

Key Concepts

  • experimental.useLightningcss: boolean; default false, o que faz webpack usar PostCSS + postcss-preset-env. Setar true desabilita PostCSS em favor do Lightning CSS.
  • Turbopack sempre usa Lightning CSS: essa flag é ignorada pelo Turbopack (não afeta nada lá).
  • lightningCssFeatures: { include, exclude } (arrays de strings) para forçar features CSS específicas a sempre/nunca ser transpiladas, independente do browserslist target. Aplica-se tanto ao webpack (com useLightningcss: true) quanto ao Turbopack.

Code Examples

const nextConfig: NextConfig = {
  experimental: {
    useLightningcss: true, // desabilita PostCSS no webpack
    lightningCssFeatures: {
      include: ['light-dark', 'oklab-colors'],
      exclude: ['nesting'],
    },
  },
}
  • O que demonstra: liga Lightning CSS no webpack e força a transpilação de light-dark/oklab-colors mesmo que os targets do browserslist já suportem, enquanto exclui nesting da transpilação mesmo sem suporte do browser.

Reference Tables

OptionTypeDescription
includestring[]Features a sempre transpilar, independente dos browser targets.
excludestring[]Features a nunca transpilar, mesmo que os browser targets exigissem.

Features individuais suportadas: nesting, not-selector-list, dir-selector, lang-selector-list, is-selector, text-decoration-thickness-percent, media-interval-syntax, media-range-syntax, custom-media-queries, clamp-function, color-function, oklab-colors, lab-colors, p3-colors, hex-alpha-colors, space-separated-color-notation, font-family-system-ui, double-position-gradients, vendor-prefixes, logical-properties, light-dark.

Grupos compostos: selectors (nesting, not-selector-list, dir-selector, lang-selector-list, is-selector), media-queries (media-interval-syntax, media-range-syntax, custom-media-queries), colors (color-function, oklab-colors, lab-colors, p3-colors, hex-alpha-colors, space-separated-color-notation, light-dark).

VersionChanges
16.2.0lightningCssFeatures added.
15.1.0Suporte a useSwcCss removido do Turbopack.
14.2.0Processador CSS default do Turbopack mudou de @swc/css para Lightning CSS; useLightningcss passou a ser ignorado no Turbopack.

Anti-patterns

  • Esperar que useLightningcss: false afete o Turbopack: a flag é ignorada lá, Turbopack sempre usa Lightning CSS independente dessa config.

Key Takeaways

  1. No webpack, decisão binária: PostCSS (default) vs Lightning CSS (useLightningcss: true).
  2. No Turbopack, não há escolha, é sempre Lightning CSS desde 14.2.0.
  3. lightningCssFeatures é a única parte desta página que também vale para Turbopack.
  4. Por default, quais features transpilar é decidido pelo target do browserslist; include/exclude sobrescrevem isso manualmente.

Connects To

  • turbopack: Turbopack já embute Lightning CSS por padrão, sem opção de configurar aqui.
AnteriorurlImportsPróximouseOffline