nextjs - 💡(How to fix) Fix Turbopack + Lightning CSS: `lightningCssFeatures.include: ['custom-media-queries']` does not expand `@custom-media` — `ParserFlags::CUSTOM_MEDIA` is never set [1 comments, 2 participants]

Link to the code that reproduces this issue

https://github.com/

To Reproduce

1. next.config.ts:

   import type { NextConfig } from 'next';
   
   const nextConfig: NextConfig = {
     experimental: {
       useLightningcss: true,
       lightningCssFeatures: {
         include: ['custom-media-queries'],
       },
     },
   };
   
   export default nextConfig;

2. app/page.module.css:

   @custom-media --md (min-width: 62em);
   
   .root {
     display: flex;
     align-items: center;
     min-height: 100vh;
   
     @media (--md) {
       display: none;
     }
   }

3. app/page.tsx:

   import styles from './page.module.css';
   export default function Home() {
     return <div className={styles.root}>Resize me</div>;
   }

4. Run next build (Turbopack is the default) and inspect the emitted CSS in .next/static/chunks/*.css.

Current vs. Expected behavior

Current (reproduced on 16.2.4 stable and 16.3.0-canary.2):

The emitted CSS preserves @custom-media declarations and leaves @media (--md) references unresolved. No browser natively understands these, so the media query never matches:

@custom-media --md (min-width: 62em);
.page-module__…__root{display:flex;align-items:center;min-height:100vh}
@media (--md){.page-module__…__root{display:none}}

Expected — @custom-media declarations are stripped and @media (--md) is replaced with the resolved condition:

.page-module__…__root{display:flex;align-items:center;min-height:100vh}
@media (width >= 62em){.page-module__…__root{display:none}}

This matches the docs for lightningCssFeatures, which list custom-media-queries as a supported individual feature (mapped to @custom-media rules).

Root cause

Lightning CSS needs two flags to transpile @custom-media:

1. ParserFlags::CUSTOM_MEDIA on the parser — otherwise @custom-media rules are parsed as UnknownAtRule and preserved verbatim.
2. Features::CustomMediaQueries in Targets.include on the transformer — so the rules get downleveled.

Turbopack sets only #2. In turbopack/crates/turbopack-css/src/process.rs, process_content builds ParserOptions like this:

let config = ParserOptions {
    css_modules: match ty { /* … */ },
    filename: filename.to_string(),
    error_recovery: true,
    ..Default::default()   // flags: ParserFlags::empty()  ← the bug
};

get_lightningcss_browser_targets in the same file correctly ORs Features::CustomMediaQueries into Targets.include, but that only controls downleveling; it never turns on the parser flag. grep across turbopack/crates/turbopack-css/ for ParserFlags, CUSTOM_MEDIA, Drafts, custom_media returns zero matches.

Direct verification via the bundled N-API binding

Calling the same Lightning CSS transform Next.js ships — first without, then with drafts.customMedia:

const { lightningcssFeatureNamesToMaskNapi, lightningCssTransform } =
  require('@next/swc-linux-x64-gnu/next-swc.linux-x64-gnu.node');

const input = `
@custom-media --md (min-width: 62em);
.root { display: flex; @media (--md) { display: none; } }
`;
const mask = lightningcssFeatureNamesToMaskNapi(['custom-media-queries']); // 256

// What Next.js does today:
lightningCssTransform({
  filename: 'test.css', code: Buffer.from(input),
  include: (1 | mask) >>> 0, exclude: 0,
}).code.toString();
// @custom-media --md (min-width: 62em);
// .root { display: flex; }
// @media (--md) { .root { display: none; } }   ← broken

// With drafts / ParserFlags::CUSTOM_MEDIA enabled:
lightningCssTransform({
  filename: 'test.css', code: Buffer.from(input),
  include: (1 | mask) >>> 0, exclude: 0,
  drafts: { customMedia: true },
}).code.toString();
// .root { display: flex; }
// @media (width >= 62em) { .root { display: none; } }   ← expected

Related PR and missing test

The lightningCssFeatures option was added in #90901 (released in 16.2.0). The PR routes feature-name bitflags into Targets { include, exclude } but does not touch ParserOptions.flags. The e2e fixtures under test/e2e/app-dir/experimental-lightningcss-features*/ cover only light-dark and nesting; there is no test for custom-media-queries.

Suggested fix

In process_content, derive ParserFlags from feature_flags.include:

use lightningcss::stylesheet::ParserFlags;
use lightningcss::targets::Features;

let mut parser_flags = ParserFlags::empty();
if feature_flags.include & Features::CustomMediaQueries.bits() != 0 {
    parser_flags |= ParserFlags::CUSTOM_MEDIA;
}

let config = ParserOptions {
    css_modules: /* … */,
    filename: filename.to_string(),
    error_recovery: true,
    flags: parser_flags,
    ..Default::default()
};

Provide environment information

Operating System:
  Platform: linux
  Arch: x64
Binaries:
  Node: 24.8.0
  npm: 11.6.0
Relevant Packages:
  next: 16.2.4 (also reproduced on 16.3.0-canary.2)
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: 5.9.3
Next.js Config:
  experimental.useLightningcss: true
  experimental.lightningCssFeatures.include: ['custom-media-queries']

Which area(s) are affected? (Select all that apply)

CSS, Turbopack

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local), next start (local)

Additional context

Verified on both 16.2.4 (stable) and 16.3.0-canary.2. The feature was introduced in 16.2.0 via #90901, and the missing ParserFlags::CUSTOM_MEDIA has been there since. Direct invocation of the bundled native binding (shown above) confirms the underlying Lightning CSS transform works correctly once drafts.customMedia: true / ParserFlags::CUSTOM_MEDIA is set — the issue is purely in how Turbopack wires up ParserOptions.