docs: clarify behavior of externalsType "module-import" with dynamic chunks

[Bhumi0189]

This PR clarifies how externalsType: "module-import" behaves with dynamic imports.

Currently, it may be surprising that an external used only in a dynamically imported chunk is hoisted into the entry chunk. This happens because module-import externals are emitted as static ESM imports and participate in the module linking phase rather than chunk execution.

This documentation update explains that distinction to reduce confusion for developers encountering this behavior.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
webpack-js-org	Ready	Preview, Comment	Jan 27, 2026 6:18pm

[Bhumi0189]

I've just opened a documentation PR to clarify this behavior in the Webpack docs.

When using externalsType: "module-import", externals are emitted as static ESM imports that participate in the module linking phase. This means they must be available at link time, even if the execution dependency exists only in a dynamic chunk.

This is the expected behavior—it ensures correct ESM semantics. The import statement needs to be in the entry chunk so the module linking can resolve the external at parse time.

The new documentation explains:

• Why hoisting occurs with module-import externals
• How this differs from regular chunk-level dependencies
• Why this is necessary for proper ESM linking

This should help other developers understand why this happens and that it's by design, not a bug. 📖

[alexander-akait]

Sorry, we should improve it in webpack itself, not document it, it is a feature

[Bhumi0189]

Thanks for the clarification — that makes sense.

In that case, would an improvement such as a compilation warning or informational message (e.g., in stats output or verbose mode) be appropriate when externalsType: "module-import" causes an external referenced only in async chunks to be emitted in the entry chunk?

That could help developers understand that this is due to ESM linking semantics rather than chunk dependency behavior.

I’d be happy to work on a PR in webpack core if this direction sounds reasonable.

[alexander-akait]

We don't need to document something here, we need to improve our generator logic to generate import inside dynamic chuck, that is all