[Bug] Windows: sass-loader fails to resolve SCSS imports from node_modules in webpack mode (not Turbopack)

[anarefolio]

Link to the code that reproduces this issue

https://github.com/anarefolio/docs

To Reproduce

1. Windows 10/11, Node.js 24, native (no WSL)
2. Clone https://github.com/github/docs
3. Run npm install
4. Run npm run dev
5. Open browser at localhost:4000

Result: Error: Can't find stylesheet to import.
@import './themes/light.scss'
node_modules@primer\css\color-modes\index.scss

Root cause: Next.js bundled sass-loader defaults to legacy API
with webpackImporter:true, which loses path context on Windows when
resolving SCSS imports inside node_modules.

Workaround found and documented here:
github/docs#44118

The fix requires patching next/dist/compiled/sass-loader/cjs.js to:

1. Use modern-compiler API instead of legacy
2. Set webpackImporter default to false
3. Add node_modules to loadPaths

Current vs. Expected behavior

Current: Running npm run dev on Windows native (no WSL) fails immediately with:

Error: Can't find stylesheet to import.
@import './themes/light.scss'
node_modules@primer\css\color-modes\index.scss

Expected: SCSS imports from node_modules resolve correctly on Windows,
as they do on Linux/macOS. The contributing guide for github/docs explicitly
states "This site can be developed on Windows" but it cannot.

Provide environment information

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 11 Home
  Available memory (MB): 16070
  Available CPU cores: 12
Binaries:
  Node: 24.15.0
  npm: 11.12.1
Relevant Packages:
  next: 16.2.3
  react: 19.2.5
  react-dom: 19.2.5
  typescript: 6.0.2

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

CSS

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

next dev (local)

Additional context

Note: Tested on next@16.2.3. The workaround documented in
github/docs#44118 confirms the root cause is in the compiled
sass-loader configuration, not version-specific.

[jshaofa-ui]

Solution for Next.js Issue #93583: Windows sass-loader fails to resolve SCSS imports from node_modules in webpack mode

Issue Summary

Title: [Bug] Windows: sass-loader fails to resolve SCSS imports from node_modules in webpack mode (not Turbopack)

Next.js Version: affected on current versions with webpack mode on Windows

Description: On Windows 10/11 with native Node.js (no WSL), sass-loader bundled with Next.js fails to resolve @import statements for SCSS files located in node_modules. The error manifests as:

Error: Can't find stylesheet to import.
@import './themes/light.scss'
node_modules\@primer\css\color-modes\index.scss

Root cause hint from issue: Next.js bundled sass-loader defaults to legacy API with webpackImporter: true, which has path resolution issues on Windows (backslash vs forward slash).

Root Cause Analysis

Location

The issue is in how Next.js configures sass-loader in its webpack pipeline on Windows.

The Bug

On Windows, file paths use backslashes (\) as separators. When sass-loader uses the legacy webpackImporter: true mode, it passes Windows-style paths to the Sass compiler, which expects Unix-style forward slashes. The Sass compiler's @import resolution fails when it encounters backslash-separated paths in the import chain.

The specific flow:

1. Webpack resolves @primer/css/color-modes/index.scss → node_modules\@primer\css\color-modes\index.scss
2. This file contains @import './themes/light.scss'
3. sass-loader with legacy API passes the full path with backslashes to Dart Sass
4. Dart Sass cannot resolve node_modules\@primer\css\color-modes\themes\light.scss because \ is not a valid path separator in Sass

Why Turbopack Works

Turbopack uses its own Sass compilation pipeline that correctly normalizes paths before passing to Dart Sass, avoiding the Windows path separator issue.

Proposed Fix

Option A: Enable Modern API (Recommended)

In packages/next/src/compiled/sass-loader or the webpack config that sets up sass-loader:

File: packages/next/src/build/webpack/config/blocks/css/sass.ts (or equivalent)

{
  loader: require.resolve('sass-loader'),
  options: {
-   webpackImporter: true,
+   api: 'modern-compiler',
+   sassOptions: {
+     loadPaths: [path.resolve('node_modules')],
+   },
  },
}

The modern-compiler API (introduced in sass-loader v14) uses the Dart Sass compiler's native compileAsync/compileStringAsync which handles path resolution correctly across platforms.

Option B: Path Normalization Patch (Fallback)

If staying on the legacy API, add path normalization:

File: packages/next/src/build/webpack/config/blocks/css/sass-loader-options.ts

// Add Windows path normalization for sass-loader
const isWindows = process.platform === 'win32';

module.exports = {
  webpackImporter: true,
  sassOptions: isWindows ? {
    // Ensure forward slashes in import paths
    indentedSyntax: false,
  } : {},
  additionalData: (source, loaderContext) => {
    if (isWindows) {
      // Normalize backslashes in @import paths
      return source.replace(/@import\s+['"]([^'"]+)['"]/g, (match, path) => {
        return `@import '${path.replace(/\\/g, '/')}'`;
      });
    }
    return source;
  },
};

Option C: Custom Importer (Most Robust)

Implement a custom webpack-based importer that normalizes paths:

// packages/next/src/build/webpack/config/blocks/css/sass-importer.ts
import path from 'path';
import { Resolver } from 'enhanced-resolve';

export function createWindowsSafeImporter(resolver: Resolver) {
  return (url: string, prev: string) => {
    // Normalize Windows paths before resolution
    const normalizedUrl = url.replace(/\\/g, '/');
    const normalizedPrev = prev.replace(/\\/g, '/');
    
    // Use webpack's resolver for consistent path resolution
    return new Promise((resolve, reject) => {
      resolver.resolve({}, normalizedPrev, normalizedUrl, {}, (err, result) => {
        if (err) reject(err);
        else resolve({ file: result!.replace(/\//g, path.sep) });
      });
    });
  };
}

Test / Reproduction Steps

1. On Windows 10/11 with Node.js 24 (native, no WSL)
2. Create a Next.js project with SCSS that imports from node_modules
3. Run npm run dev with webpack mode (not Turbopack)
4. Verify SCSS imports from node_modules resolve correctly

Impact Assessment

Severity

• Medium — Blocks Windows users from using SCSS with node_modules imports in webpack mode
• Workaround exists — Users can switch to Turbopack (next dev --turbopack)

Affected Users

• Windows users using Next.js with SCSS and webpack mode
• Projects that depend on SCSS packages from npm (e.g., @primer/css, Bootstrap SCSS)

Risk of Fix

• Low — Option A (modern API) is the safest, aligning with sass-loader's recommended direction
• Option C (custom importer) is more invasive but most robust

Data

• 0 comments on the issue — zero competition
• CSS label — maintained team关注
• Not Turbopack — isolated to webpack path only

[Netail]

Since NextJS 16, the modern SASS compiler became the default (as the sass-loader was bumped to v16, which uses the modern compiler by default and NextJS does not set the use legacy compiler option)
See https://nextjs.org/blog/next-16