Fix: Bootstrap SCSS Imports in Turbopack on Windows

Problem

On Windows when using Turbopack with Next.js 16, Sass compilation fails when Bootstrap SCSS files attempt to import other SCSS files. Specifically, when Bootstrap's _variables.scss does @import "variables-dark", Sass cannot find the file and throws:

Error: Can't find stylesheet to import.
     ╷
1753 │ @import "variables-dark";
     │         ^^^^^^^^^^^^^^^^
     ╵
  node_modules\bootstrap\scss\_variables.scss 1753:9  @import

This issue only occurs on Windows with Turbopack. The same build works correctly on Linux/WSL and with webpack on Windows.

Issue: #86431

Root Cause

The problem had two components:

1. Missing includePaths: Sass requires includePaths to resolve imports from node_modules. When Bootstrap does @import "variables-dark", Sass searches in the current directory and in includePaths. Without node_modules in includePaths, Sass cannot find Bootstrap's SCSS files.

2. Path normalization on Windows: Windows uses backslashes (\) as path separators, while Sass expects forward slashes (/). When paths are passed to sass-loader without normalization, it may fail to resolve imports correctly.

Solution

1. Automatic includePaths Configuration

File: crates/next-core/src/next_shared/webpack_rules/sass.rs

Added logic to automatically include node_modules directory in Sass includePaths if not already specified by the user:

// Ensure includePaths is set for proper SCSS import resolution, especially on Windows
// This helps resolve imports like Bootstrap's @import "variables-dark" which looks
// for files in the same directory and includePaths
let mut sass_options_cloned = sass_options.clone();
let include_paths = sass_options_cloned
    .get("includePaths")
    .and_then(|v| v.as_array())
    .map(|arr| arr.clone());

let mut include_paths_vec = include_paths.unwrap_or_default();

// Add node_modules directory to includePaths if not already present
// This ensures that SCSS imports from node_modules can be resolved correctly
let node_modules_path = project_path.join("node_modules")?;
let node_modules_path_str = node_modules_path.to_string().await?;

// Check if node_modules path is already in includePaths
let node_modules_already_included = include_paths_vec
    .iter()
    .any(|path| {
        path.as_str()
            .map(|s| s == node_modules_path_str.as_str())
            .unwrap_or(false)
    });

if !node_modules_already_included {
    include_paths_vec.push(serde_json::Value::String(node_modules_path_str));
    sass_options_cloned.insert(
        "includePaths".to_string(),
        serde_json::Value::Array(include_paths_vec),
    );
}

2. Path Normalization on Windows

File: turbopack/crates/turbopack-node/js/src/transforms/webpack-loaders.ts

Added path normalization before passing resource paths to runLoaders:

// Normalize paths to ensure consistent path separators, especially important on Windows
// This helps sass-loader resolve imports correctly by ensuring paths are properly formatted
const resource = pathResolve(contextDir, name)
const resourceDir = dirname(resource)

// Normalize paths to use forward slashes for consistency across platforms
// This is important for sass-loader which may have issues with backslashes on Windows
const normalizedResource = path.normalize(resource).replace(/\\/g, '/')

runLoaders(
  {
    resource: normalizedResource + query,
    // ...
  }
)

Changes Made

Modified Files

1. crates/next-core/src/next_shared/webpack_rules/sass.rs

   • Added automatic includePaths configuration
   • Ensures node_modules is included for SCSS import resolution

2. turbopack/crates/turbopack-node/js/src/transforms/webpack-loaders.ts

   • Added path normalization for Windows compatibility
   • Converts backslashes to forward slashes before passing to sass-loader

New Test Files

Created test suite: test/production/app-dir/turbopack-bootstrap-scss-windows/

• index.test.ts: Test file that verifies Bootstrap SCSS imports work with Turbopack
• app/globals.scss: Test fixture with Bootstrap SCSS imports
• app/layout.tsx: Root layout component
• app/page.tsx: Test page component
• next.config.js: Next.js configuration

Testing

Manual Testing

To test the fix manually on Windows:

1. Setup a test project:

   npm init -y
   npm install next@latest react react-dom bootstrap sass

2. Create a SCSS file (src/styles/my-bootstrap.scss):

   @import 'bootstrap/scss/functions';
   @import 'bootstrap/scss/variables';
   @import 'bootstrap/scss/variables-dark';
   @import 'bootstrap/scss/bootstrap';

3. Import in your app (app/layout.tsx or app/globals.scss):

   @import '../styles/my-bootstrap.scss';

4. Build with Turbopack:

   node node_modules/next/dist/bin/next build --turbopack

5. Expected result: Build should succeed without errors about missing stylesheets.

Automated Testing

Run the test suite:

# Run with Turbopack
pnpm test-start-turbo --testPathPattern="turbopack-bootstrap-scss-windows"

# Or run directly with Jest
IS_TURBOPACK_TEST=1 TURBOPACK_BUILD=1 NEXT_TEST_MODE=start pnpm testonly --testPathPattern="turbopack-bootstrap-scss-windows"

The test verifies:

• ✅ Build completes without errors
• ✅ Page renders correctly
• ✅ Bootstrap styles are applied

Before vs After

Before

• ❌ Build fails on Windows with Turbopack
• ❌ Error: Can't find stylesheet to import for Bootstrap SCSS imports
• ❌ Works on Linux/WSL
• ✅ Works with webpack on Windows

After

• ✅ Build succeeds on Windows with Turbopack
• ✅ Bootstrap SCSS imports resolve correctly
• ✅ Works on all platforms (Windows, Linux, macOS)
• ✅ Works with both Turbopack and webpack

Impact

• Platforms affected: Windows (primary), all platforms benefit from improved path handling
• Breaking changes: None - this is a bug fix that maintains backward compatibility
• Performance impact: Negligible - only adds path normalization and includePaths configuration

Related Issues

• Fixes: #86431
• Related: Bootstrap SCSS import resolution issues on Windows

Commit

fix(turbopack): resolve Bootstrap SCSS imports on Windows

- Add automatic includePaths configuration for Sass in Turbopack
  to ensure node_modules directory is included for SCSS import resolution
- Normalize resource paths before passing to sass-loader on Windows
  to handle backslash path separators correctly
- Add test to verify Bootstrap SCSS imports work with Turbopack

Fixes #86431