Skip to content

Add experimental.lightningCssModules config option#95444

Open
UditDewan wants to merge 1 commit into
vercel:canaryfrom
UditDewan:feat/lightningcss-css-modules-options
Open

Add experimental.lightningCssModules config option#95444
UditDewan wants to merge 1 commit into
vercel:canaryfrom
UditDewan:feat/lightningcss-css-modules-options

Conversation

@UditDewan

Copy link
Copy Markdown

What?

Adds a new experimental config option, experimental.lightningCssModules, that exposes Lightning CSS's CSS Modules options when bundling with Turbopack:

// next.config.ts
const nextConfig = {
  experimental: {
    lightningCssModules: {
      // custom naming pattern for scoped class names
      pattern: 'my-company-[hash]-[local]',
      // keep authored @keyframes names instead of scoping them
      animation: false,
    },
  },
}

Supported options: pattern (custom naming patterns) and the feature-scoping toggles animation, grid, customIdents, dashedIdents, container (turning off feature scoping).

Why?

Turbopack always processes CSS Modules with Lightning CSS using a hardcoded configuration ([name]__[hash]__[local] pattern, animation scoping on). Users repeatedly asked in discussion #64580 for a way to:

  • specify the CSS Modules class naming pattern / hash names
  • disable feature scoping, particularly @keyframes renaming, to match webpack's css-loader behavior when migrating to Turbopack

experimental.lightningCssFeatures (#90901) only controls feature transpilation flags and does not cover CSS Modules options, so there is currently no escape hatch at all on Turbopack.

How?

  • New CssModulesOptions struct in turbopack-css, threaded NextConfig → CssOptionsContext → ModuleType::Css → CssModule → parse_css/process_content, following the same path as lightningcss_features (Add experimental.lightningCssFeatures config option #90901).
  • All fields are optional; unset fields fall back to the previously hardcoded values ([name]__[hash]__[local], animation: true, grid: false, customIdents: true, dashedIdents: false, container: false), so behavior is unchanged unless configured.
  • A custom pattern is validated once at config level so a typo produces a single clear error naming the config key instead of one error per CSS file. The pattern string is interned so the parsed Pattern can borrow into the 'static parser options stored in ParseCssResult.
  • webpack does not use Lightning CSS for CSS Modules name scoping (css-loader handles that and is already configurable), so this option is Turbopack-only; a warning is logged when it is set with another bundler.
  • Turbopack-only e2e test covering the custom pattern and animation: false, plus documentation in useLightningcss.mdx.

Addresses the CSS Modules configuration requests in #64580.

Allows configuring how lightningcss processes CSS Modules in Turbopack:
a custom naming pattern for scoped class names and toggles for scoping
@Keyframes names, grid line names, custom idents, dashed idents, and
@container names. Defaults preserve the previously hardcoded behavior.
@puopg

puopg commented Jul 3, 2026

Copy link
Copy Markdown

🙌

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants