Troubleshooting Guide

Prerequisites

exposes need to be processed by multiple builders

As shown in how the @module-federation/vite plugin works: shared libs are all processed by the builder in the adapter, such as esbuild.

In dev, exposes are forwarded by the vite server, so they are processed by vite rather than by the builder in the adapter; they are only processed by esbuild during build.

So when verifying scenarios, you need to verify the dev scenario and the build scenario separately.

Configuring shared does not mean the dependency will actually be shared

Because of vite alias, if you also enable alias for a dependency when starting the service (including alias in tsconfig or in vite), the dependency will point to different files, and some dependencies will fail to be shared, such as @vue/composition-api.

The reason sharing fails is:

The dependency defines a global Symbol constant in IIFE form within the file, and the Symbol values in multiple copies of the dependency differ, causing various problems such as dependency errors, loss of reactivity, and so on.

Imported module names

Shared dependencies are added as external in the @module-federation/vite plugin, and at that point vite resolves them into the form /base/${moduleName}. The plugin then performs a transform replacement on the imported module name.

URLs of imported files

Because dependency loading relies on the importmap feature, which has poor browser compatibility, older versions cannot handle it well.

native-federation internally integrates the es-module-shim dependency, which is needed to make the importmap feature compatible through es-module-shim.

The corresponding imported file URL is resolved and processed in es-module-shim.

Meanwhile, considering the performance cost of using new URL directly, es-module-shim tokenizes and parses addresses on its own, which means there may be uncovered scenarios that cause URL resolution anomalies, leading to incorrect final request addresses.

Common issues

Styles in remote differ from the remote styles loaded in host

Check the dependency relationships

Because remote exports go through a build, a corresponding import is required to declare the relationship before it can be exported together during the build.

So first check whether the styles in remote are injected globally. If the global injection needs modification, you only need to let the build tool recognize the dependency. Options are as follows:

• Write an import statement to declare the dependency relationship (recommended).
• Share the global injection logic across all services.
• Handle it in a plugin, adding the corresponding module export to every build.

Check the network requests

Static asset paths are modified during the build. Since the host, baseUrl, and so on differ across microservice builds, the static asset paths may fail to resolve after the build, causing resource loading failures. See the Static asset URL resolution errors section below.

Import statements disappear after the build

Because remote is built using the adapter (currently there is only the esbuild adapter, so this is equivalent to building with esbuild directly), you need to check how the esbuild build handles the corresponding imports.

You can use the ESBuild Playground to try reproducing it. If esbuild cannot parse the module, you need a plugin to convert the resource into a module that esbuild can recognize, see issue: support inline css.

A third-party library fails to load, reporting Uncaught (in promise) SyntaxError: The requested module 'blob:http://${host}/${uuid}' does not provide an export named '${varName}'

Check whether the third-party package contains the corresponding export

Some third-party packages are esm without a single entry, or the entry they provide is incomplete.

According to how the @module-federation/vite plugin works, the tool builds the third-party package entry (fields such as main in package.json).

During the build process, imports and exports of non-entry modules are converted into other syntax, such as __export(), __reExport(), defineProperties, and so on. So if something is only exported in an internal module and not exported by the entry file, accessing the entry directly after the build will not get the corresponding export content.

This is what causes the export named error after the build.

Incorrect shared libs configuration

In most cases, the dependency that reports the error is a shared library.

You can use Chrome's Source panel to check whether the built content is correct:

1. There are no extra imports besides the shared lib (some packages are declared as peers and ignored during the build, resulting in abnormal build output).
2. It does not import itself (such as importing my-components/Button inside my-components).
3. Among the imported non-shared libs, there is no file singleton (that is, a file that directly defines a variable as a singleton, such as a file containing const foo = 'bar'; export { foo }, where foo is a file singleton).

In most cases, sharing anomalies are caused by the problems above.

Third-party library URL resolution errors

1. Check whether the importmap registered in the html matches the URL actually requested in the network, and whether it is correct.
2. If they do not match, it may be the influence of alias; check the alias configuration in configuration files such as vite.config.ts and tsconfig.json.
3. If it is incorrect, you can modify the es-module-shim configuration and configure a custom resolve to check whether the resolution is correct.
4. If the resolved URL is wrong but the source address is correct, submit an issue to the es-module-shims repository.
5. If the source address is wrong, check which file sent the request and whether the URL in that file is correct.

Static asset URL resolution errors

1. Check whether the static asset URL is correct.
2. If it is incorrect, check where the request is sent from (some requests are sent by the browser rather than by es-module-shim).
3. If the request is sent by the browser, you need a reverse proxy to forward the request, or fix the resource address to a complete URL instead of a relative or absolute path.
4. If the request is sent by es-module-shim, configure a custom resolve to check whether the resolution is correct.
5. If the resolved URL is wrong but the source address is correct, submit an issue to the es-module-shims repository.
6. If the source address is wrong, check which file sent the request and whether the URL in that file is correct.

A feature does not take effect after the build, but works in dev

1. Inspect the build output separately and confirm the following checklist:
   • Whether the corresponding feature code is missing from the output.
   • Whether the output reports errors at runtime.
   • Whether the output requires a corresponding plugin for processing, such as vue needing esbuild-vue.
   • Whether the plugin's processing result meets expectations; for example, esbuild-vue inlines css by default, which causes esbuild not to build the css code, so you need to manually declare { extractCss: true }.
2. For missing code, refer to Styles in remote differ from the remote styles loaded in host to troubleshoot.
3. For runtime errors, troubleshoot according to the specific problem; refer to Common issues.