add support for cssmodules-pure-no-check to allow global CSS features like View Transitions (#77321)

jantimon · samcx · web-flow · commit ebc1150c8274 · 2025-04-02T08:43:26.000-07:00
## What? This PR adds support for `cssmodules-pure-no-check` in CSS Modules by upgrading `postcss-modules-local-by-default` from 4.0.4 to 4.2.0 (`cssmodules-pure-no-check` was also recently [merged into LightningCSS 1.29.3](parcel-bundler/lightningcss#898)) ## Why? Global CSS selectors like View Transitions API require global scope to work properly. Currently, there's no clean way to use these selectors with CSS Modules in Next.js, which causes issues when: 1. Using the View Transitions API 2. Migrating from css-in-js libraries like styled-components to React Server Components with CSS Modules ## How? - Upgrades `postcss-modules-local-by-default` to 4.2.0 - Adds support for the `/* cssmodules-pure-no-check */` comment pattern in CSS files which disables CSS Modules localization for that file - This mirrors established escape hatches in other tools (`@ts-nocheck`, `/* eslint-disable */`) - Added tests (similar to one @samcx wrote previously) to ensure functionality works correctly The approach was previously approved by @samcx in issue #77232, who mentioned that LightningCSS was already bumped, but we needed to bump the PostCSS side Fixes #77232 --------- Co-authored-by: Sam Ko <sam@vercel.com>
diff --git a/packages/next/package.json b/packages/next/package.json
@@ -293,7 +293,7 @@
     "picomatch": "4.0.1",
     "postcss-flexbugs-fixes": "5.0.2",
     "postcss-modules-extract-imports": "3.0.0",
-    "postcss-modules-local-by-default": "4.0.4",
+    "postcss-modules-local-by-default": "4.2.0",
     "postcss-modules-scope": "3.0.0",
     "postcss-modules-values": "4.0.0",
     "postcss-preset-env": "7.4.3",
diff --git a/packages/next/src/compiled/postcss-modules-local-by-default/index.js b/packages/next/src/compiled/postcss-modules-local-by-default/index.js
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/e2e/app-dir/css-modules-pure-no-check/app/home.module.css b/test/e2e/app-dir/css-modules-pure-no-check/app/home.module.css
@@ -0,0 +1,19 @@
+/* cssmodules-pure-no-check */
+
+/* View Transitions API - requires global scope to work properly */
+:global(::view-transition-old(root)) {
+  animation-duration: 0.3s;
+}
+
+/* a local class */
+.home {
+  background-color: #f0f0f0;
+  color: #333;
+  font-size: 16px;
+  padding: 20px;
+}
+
+/* a global class */
+:global(.global) {
+  font-weight: 700;
+}
diff --git a/test/e2e/app-dir/css-modules-pure-no-check/app/layout.tsx b/test/e2e/app-dir/css-modules-pure-no-check/app/layout.tsx
@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react'
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: ReactNode
+}>) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
diff --git a/test/e2e/app-dir/css-modules-pure-no-check/app/page.tsx b/test/e2e/app-dir/css-modules-pure-no-check/app/page.tsx
@@ -0,0 +1,9 @@
+import styles from './home.module.css'
+
+export default function Home() {
+  return (
+    <div id="my-div" className={`${styles.home} global`}>
+      <div>This text should be bold</div>
+    </div>
+  )
+}
diff --git a/test/e2e/app-dir/css-modules-pure-no-check/css-modules-pure-no-check.test.ts b/test/e2e/app-dir/css-modules-pure-no-check/css-modules-pure-no-check.test.ts
@@ -0,0 +1,37 @@
+import { nextTestSetup } from 'e2e-utils'
+import cheerio from 'cheerio'
+
+describe('css-modules-pure-no-check', () => {
+  const { isNextStart, next } = nextTestSetup({
+    files: __dirname,
+  })
+
+  it('should apply styles correctly', async () => {
+    const browser = await next.browser('/')
+
+    const elementWithGlobalStyles = await browser
+      .elementByCss('#my-div')
+      .getComputedCss('font-weight')
+
+    expect(elementWithGlobalStyles).toBe('700')
+  })
+
+  if (isNextStart) {
+    it('should have emitted a CSS file', async () => {
+      const html = await next.render('/')
+      const $html = cheerio.load(html)
+
+      const cssLink = $html('link[rel="stylesheet"]')
+      expect(cssLink.length).toBe(1)
+      const cssHref = cssLink[0].attribs['href']
+
+      const res = await next.fetch(cssHref)
+      const cssCode = await res.text()
+
+      expect(cssCode).toInclude(`.global{font-weight:700}`)
+      expect(cssCode).toInclude(
+        `::view-transition-old(root){animation-duration:.3s}`
+      )
+    })
+  }
+})
diff --git a/test/e2e/app-dir/css-modules-pure-no-check/next.config.ts b/test/e2e/app-dir/css-modules-pure-no-check/next.config.ts
@@ -0,0 +1,7 @@
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  /* config options here */
+}
+
+export default nextConfig
diff --git a/test/integration/css-fixtures/cssmodules-pure-no-check/pages/index.module.css b/test/integration/css-fixtures/cssmodules-pure-no-check/pages/index.module.css
@@ -0,0 +1,19 @@
+/* cssmodules-pure-no-check */
+
+/* View Transitions API - requires global scope to work properly */
+:global(::view-transition-old(root)) {
+  animation-duration: 0.3s;
+}
+
+/* a local class */
+.home {
+  background-color: #f0f0f0;
+  color: #333;
+  font-size: 16px;
+  padding: 20px;
+}
+
+/* a global class */
+:global(.global) {
+  font-weight: 700;
+}
diff --git a/test/integration/css-fixtures/cssmodules-pure-no-check/pages/index.tsx b/test/integration/css-fixtures/cssmodules-pure-no-check/pages/index.tsx
@@ -0,0 +1,9 @@
+import styles from './index.module.css'
+
+export default function Home() {
+  return (
+    <div id="my-div" className={`${styles.home} global`}>
+      <div>This text should be bold</div>
+    </div>
+  )
+}
diff --git a/test/integration/css-fixtures/cssmodules-pure-no-check/tsconfig.json b/test/integration/css-fixtures/cssmodules-pure-no-check/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "noEmit": true,
+    "incremental": true,
+    "module": "esnext",
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": ["next-env.d.ts", ".next/types/**/*.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}
diff --git a/test/integration/css-modules/test/index.test.js b/test/integration/css-modules/test/index.test.js
@@ -724,3 +724,59 @@ describe('Catch-all Route CSS Module Usage', () => {
     }
   )
 })
+
+describe('cssmodules-pure-no-check usage', () => {
+  const appDir = join(fixturesDir, 'cssmodules-pure-no-check')
+
+  let stdout
+  let code
+  let app
+  let appPort
+
+  beforeAll(async () => {
+    await remove(join(appDir, '.next'))
+    ;({ code, stdout } = await nextBuild(appDir, [], {
+      stdout: true,
+    }))
+    appPort = await findPort()
+    app = await nextStart(appDir, appPort)
+  })
+
+  afterAll(() => killApp(app))
+
+  it('should have compiled successfully', () => {
+    console.log(stdout)
+    expect(code).toBe(0)
+    expect(stdout).toMatch(/Compiled successfully/)
+  })
+
+  it('should apply styles correctly', async () => {
+    const browser = await webdriver(appPort, '/')
+
+    const elementWithGlobalStyles = await browser
+      .elementByCss('#my-div')
+      .getComputedCss('font-weight')
+
+    expect(elementWithGlobalStyles).toBe('700')
+  })
+
+  it(`should've emitted a CSS file`, async () => {
+    const content = await renderViaHTTP(appPort, '/')
+    const $ = cheerio.load(content)
+
+    const cssSheet = $('link[rel="stylesheet"]')
+    expect(cssSheet.length).toBe(1)
+    const stylesheet = cssSheet[0].attribs['href']
+
+    const cssContent = await fetchViaHTTP(appPort, stylesheet).then((res) =>
+      res.text()
+    )
+
+    const cssCode = cssContent.replace(/\/\*.*?\*\//g, '').trim()
+
+    expect(cssCode).toInclude(`.global{font-weight:700}`)
+    expect(cssCode).toInclude(
+      `::view-transition-old(root){animation-duration:.3s}`
+    )
+  })
+})
