nextjs - 💡(How to fix) Fix External modules not supported in subpath imports [1 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#91738Fetched 2026-04-08 01:07:08
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
Participants
Timeline (top)
labeled ×2issue_type_added ×1subscribed ×1

Error Message

  1. You will get the error Module not found: Can't resolve '#image'

Code Example

// package.json
{
  // ...
  "imports": {
    "#image": "next/image"
  }
}

// page.tsx
import Image from "#image";

---

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.6.0: Fri Jul  5 17:56:39 PDT 2024; root:xnu-10063.141.1~2/RELEASE_ARM64_T8122
  Available memory (MB): 24576
  Available CPU cores: 8
Binaries:
  Node: 23.11.1
  npm: 10.9.2
  Yarn: 1.22.22
  pnpm: 10.25.0
Relevant Packages:
  next: 16.2.0 // Latest available version is detected (16.2.0).
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  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/ysulyma/nextjs-subpath-imports-external-bug

To Reproduce

  1. Start the application in development (next dev)
  2. You will get the error Module not found: Can't resolve '#image'
<img width="1001" height="384" alt="Image" src="https://github.com/user-attachments/assets/023b1210-c6cb-44f0-89cf-34ff150ee319" />

Current vs. Expected behavior

Node.js docs specify that imports field is allowed to map to external packages: https://nodejs.org/api/packages.html#subpath-imports, however this does not work.

// package.json
{
  // ...
  "imports": {
    "#image": "next/image"
  }
}

// page.tsx
import Image from "#image";

I originally encountered this issue while trying to get MathJax to server-render; they have imports in the above style as you can see from their package.json.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.6.0: Fri Jul  5 17:56:39 PDT 2024; root:xnu-10063.141.1~2/RELEASE_ARM64_T8122
  Available memory (MB): 24576
  Available CPU cores: 8
Binaries:
  Node: 23.11.1
  npm: 10.9.2
  Yarn: 1.22.22
  pnpm: 10.25.0
Relevant Packages:
  next: 16.2.0 // Latest available version is detected (16.2.0).
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: 5.9.3
Next.js Config:
  output: N/A

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

Module Resolution, Turbopack

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

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

Additional context

No response

extent analysis

Fix Plan

To resolve the issue with subpath imports, we need to configure Next.js to properly handle the imports field in package.json.

Here are the steps:

  • Update next.config.js to include the experimental.resolver option.
  • Use the resolve function from enhanced-resolve to customize the resolution of modules.

Example Code

// next.config.js
const { resolve } = require('enhanced-resolve');

module.exports = {
  //... other configurations ...
  experimental: {
    resolver: async (options) => {
      const { resolver } = options;
      return {
        ...resolver,
        resolve: async (ctx, opts) => {
          const imports = ctx.packageJSON.imports;
          if (imports && opts.path in imports) {
            opts.path = imports[opts.path];
          }
          return resolver.resolve(ctx, opts);
        },
      };
    },
  },
};

Verification

After applying the fix, run next dev and verify that the application starts without errors. The Module not found: Can't resolve '#image' error should be resolved.

Extra Tips

  • Make sure to update next and react to the latest versions to ensure compatibility with the experimental.resolver option.
  • If you're using a custom webpack configuration, you may need to modify it to work with the experimental.resolver option.

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…

Still need to ship something?

×6

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

Back to top recommendations

TRENDING