Issue Station
Sign In
Tools hereToolbox

nextjs - ✅(Solved) Fix Sass breaks when path aliases start with `#` [1 pull requests, 2 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#87161•Fetched 2026-04-08 02:07:39
View on GitHub
Comments
2
Participants
2
Timeline
12
Reactions
0
Author
poradaporada
Participants
686f6c61686f6c61poradaporada
Timeline (top)
labeled ×4commented ×2subscribed ×2cross-referenced ×1

Error Message

Error: The default namespace "" is not a valid Sass identifier.

Recommendation: add an "as" clause to define an explicit namespace. ╷ 1 │ @use "#stylesheets/foo"; │ ^^^^^^^^^^^^^^^^^^^^^^^

Fix Action

Fixed

PR fix notes

PR #87206: Fix: Support path aliases starting with # in Sass imports

Description (problem / solution / changelog)

What?

Adds support for TypeScript/JavaScript path aliases in Sass @use and @import statements.

Why?

Fixes #87161

Path aliases starting with # (Node.js package imports convention) or @ were not recognized by Sass, causing build failures with error: "The default namespace '' is not a valid Sass identifier"

The issue occurs because Sass processes imports before webpack's module resolution, so it does not have access to path mappings defined in tsconfig.json or jsconfig.json.

How?

Implemented a custom Sass importer that:

  1. Reads path alias mappings from tsconfig.json/jsconfig.json via ConfigurationContext
  2. Intercepts import URLs in Sass files before the Sass compiler processes them
  3. Matches import URLs against configured patterns (exact and wildcard)
  4. Resolves aliases to absolute file system paths using the same logic as webpack
  5. Handles Sass conventions (file extensions, partial files with _)
  6. Returns file:// URLs that Sass can process

The solution works for both Webpack and Turbopack builds.

Test Plan

Added comprehensive e2e test in test/e2e/app-dir/sass-path-aliases/ that verifies:

  • Build succeeds with path aliases starting with #
  • Sass compilation completes without errors
  • Generated CSS is correctly applied

Manual testing with reproduction repository: https://github.com/porada/next-sass-path-alias-issue

Changed files

  • packages/next/src/build/webpack-config.ts (modified, +2/-0)
  • packages/next/src/build/webpack/config/blocks/css/index.ts (modified, +16/-1)
  • packages/next/src/build/webpack/config/index.ts (modified, +6/-0)
  • packages/next/src/build/webpack/config/utils.ts (modified, +4/-0)
  • packages/next/src/build/webpack/loaders/sass-importer.ts (added, +133/-0)
  • test/e2e/app-dir/sass-path-aliases/app/layout.tsx (added, +13/-0)
  • test/e2e/app-dir/sass-path-aliases/app/page.tsx (added, +10/-0)
  • test/e2e/app-dir/sass-path-aliases/package.json (added, +9/-0)
  • test/e2e/app-dir/sass-path-aliases/sass-path-aliases.test.ts (added, +47/-0)
  • test/e2e/app-dir/sass-path-aliases/styles/_variables.scss (added, +2/-0)
  • test/e2e/app-dir/sass-path-aliases/styles/globals.scss (added, +16/-0)

Code Example

git clone https://github.com/porada/next-sass-path-alias-issue.git
cd next-sass-path-alias-issue

pnpm install
pnpm build # or `pnpm dev` (will fail)

---

Error: The default namespace "" is not a valid Sass identifier.

Recommendation: add an "as" clause to define an explicit namespace.
  ╷
1 │ @use "#stylesheets/foo";
  │ ^^^^^^^^^^^^^^^^^^^^^^^

---

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:41 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6031
  Available memory (MB): 49152
  Available CPU cores: 16
Binaries:
  Node: 24.12.0
  npm: 11.7.0
  Yarn: 1.22.22
  pnpm: 10.15.1
Relevant Packages:
  next: 16.1.0-canary.20 // Latest available version is detected (16.1.0-canary.20).
  eslint-config-next: N/A
  react: 19.2.1
  react-dom: 19.2.1
  typescript: 5.9.3
Next.js Config:
  output: N/A
RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

https://github.com/porada/next-sass-path-alias-issue

To Reproduce

git clone https://github.com/porada/next-sass-path-alias-issue.git
cd next-sass-path-alias-issue

pnpm install
pnpm build # or `pnpm dev` (will fail)

If you revert the most recent commit in the test repository, pnpm build is going to succeed.

Current vs. Expected behavior

Node.js 14+ supports internal package path aliases, which are required to start with #.

Given that no other leading character is allowed, this is going to push projects away from conventional @aliases (or @/aliases) toward spec-compliant #aliases. Next.js-configured Sass currently fails to handle these paths.

With the custom alias "@stylesheets/*": ["./src/stylesheets/*"], @use "@stylesheets/foo" correctly loads the file at src/stylesheets/foo.scss.

However, when the alias is switched to "#stylesheets/*": ["./src/stylesheets/*"], Sass immediately throws an error:

Error: The default namespace "" is not a valid Sass identifier.

Recommendation: add an "as" clause to define an explicit namespace.
  ╷
1 │ @use "#stylesheets/foo";
  │ ^^^^^^^^^^^^^^^^^^^^^^^

@use "#stylesheets/foo" as foo doesn’t help either. This issue is reproducible with both Turbopack and Webpack on.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:41 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6031
  Available memory (MB): 49152
  Available CPU cores: 16
Binaries:
  Node: 24.12.0
  npm: 11.7.0
  Yarn: 1.22.22
  pnpm: 10.15.1
Relevant Packages:
  next: 16.1.0-canary.20 // Latest available version is detected (16.1.0-canary.20).
  eslint-config-next: N/A
  react: 19.2.1
  react-dom: 19.2.1
  typescript: 5.9.3
Next.js Config:
  output: N/A

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

CSS, Module Resolution, Turbopack, Webpack

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

next dev (local), next build (local), next start (local), Vercel (Deployed), Other (Deployed)

Additional context

Originally reported in sass/dart-sass#2704, but this might be Next.js’ issue.

extent analysis

TL;DR

Update Next.js to handle Node.js package path aliases starting with # or use the conventional @aliases until the issue is resolved.

Guidance

  • Verify that the issue is indeed caused by the introduction of Node.js package path aliases starting with # by reverting the recent commit and checking if pnpm build succeeds.
  • Check if there are any open issues or pull requests in the Next.js repository related to handling Node.js package path aliases starting with #.
  • Consider using the conventional @aliases instead of #aliases as a temporary workaround until the issue is resolved.
  • If using #aliases is necessary, try to find an alternative way to define the namespace in Sass, such as using a different alias or a custom loader.

Example

No code snippet is provided as the issue is related to the configuration and handling of Node.js package path aliases in Next.js and Sass.

Notes

The issue might be related to the handling of Node.js package path aliases in Next.js, and it's not clear if it's a bug or a missing feature. The conventional @aliases can be used as a temporary workaround.

Recommendation

Apply workaround: use conventional @aliases until the issue is resolved, as it is a more established and widely supported approach.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#configuration error#environment variable#network issue#logging issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

nextjs - ✅(Solved) Fix Sass breaks when path aliases start with `#` [1 pull requests, 2 comments, 2 participants]