(metro-core): add manifest SHA-256 hashes and optional bundle cache layer integration by zhongwuzw · Pull Request #4576 · module-federation/core

zhongwuzw · 2026-03-20T15:25:50Z

Description

Adds SHA-256 bundle hashes to federation manifest during bundle-remote build (metaData.buildInfo.hash, exposes[].hash, shared[].hash).
Introduces an optional runtime cache integration via global MFE_CACHE_LAYER (new ICacheLayer contract).
asyncRequire now routes remote bundle loading through the cache layer when enabled (production by default), with inflight dedup and safe fallback to loadBundleAsync on skipped.
metroCorePlugin.afterResolve extracts resolved bundle URLs (dev/prod compatible) from manifest and registers expected hashes + manifest source to the cache layer (best-effort).

Related Issue

Types of changes

Docs change / refactoring / dependency upgrade
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)

Checklist

I have added tests to cover my changes.
All new and existing tests passed.
I have updated the documentation.

…hanges

…ronous

…ration

…verification

netlify · 2026-03-20T15:25:56Z

✅ Deploy Preview for module-federation-docs ready!

Name	Link
🔨 Latest commit	`b247277`
🔍 Latest deploy log	https://app.netlify.com/projects/module-federation-docs/deploys/69c54f47d92ce80009503f85
😎 Deploy Preview	https://deploy-preview-4576--module-federation-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

changeset-bot · 2026-03-20T15:25:59Z

⚠️ No Changeset found

Latest commit: b247277

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

…tionality

…d add register function

…-download

…allback

…undle URL resolution

…equire

jbroma

hey @zhongwuzw , nice job with the implementation so far, I have few questions & one ideas about how to make this even better, let me know what you think!

jbroma · 2026-03-31T15:38:44Z

pnpm-lock.yaml

since there are no package.json changes in this PR, this is probably a leftover from previous changes, could you please verify this?

jbroma · 2026-03-31T15:46:51Z

packages/metro-core/src/commands/bundle-remote/index.ts

+      const bundleContent = await fs.readFile(
+        saveBundleOpts.bundleOutput,
+        'utf-8',
+      );


perhaps we can use bundle directly here? I don't see any benefit of reading it again from the filesystem

@jbroma Hi, I see we have --bundle-encoding in bundle-mf-remote — do we actually support non-UTF-8? https://github.com/zhongwuzw/core/blob/b2472772250dad91947eefa31b724582441f95e9/packages/metro-core/src/commands/bundle-remote/index.ts#L335

The option accepts utf8 | utf16le | ascii, but encoding info is never passed to the upload layer or stored in the manifest. The server/CDN has no idea what encoding the bundle was written in, and the client always decodes as UTF-8？ If a user passes --bundle-encoding utf16le, the bundle will silently break at runtime I think. Did I miss anything?

Probably not, it's fine to assume utf-8 for now - ideally we would store this information somewhere so we dont have to guess

jbroma · 2026-03-31T15:55:49Z

packages/metro-core/src/commands/bundle-remote/index.ts

+    // Inject container bundle hash into metaData.buildInfo.hash
+    const containerFilename = federationConfig.filename;
+    if (bundleHashMap.has(containerFilename)) {
+      rawManifest.metaData.buildInfo.hash =


is this typed in the MF core or is this a non-standard field?

shared[].hash is already typed in MF core (StatsShared.hash: string) — Metro generates it as an empty string and I populate it post-build. metaData.buildInfo.hash and expose[].hash are non-standard — StatsBuildInfo and StatsExpose don't have a hash field. Happy to add hash?: string to the core types if you'd like to formalize it.

yes, let's standardize those then 👍

jbroma · 2026-03-31T17:56:58Z

packages/metro-core/src/modules/metroCorePlugin.ts

+    afterResolve: (args) => {
+      // Register bundle hashes with cache layer for integrity verification
+      try {
+        const cacheLayer = (globalThis as any).__MFE_CACHE_LAYER__ as
+          | ICacheLayer
+          | undefined;
+        if (!cacheLayer) return args;

-    const __loadBundleAsync =
-      globalThis[`${__METRO_GLOBAL_PREFIX__ ?? ''}__loadBundleAsync`];
+        const { origin, remoteInfo, remote } = args;
+        const manifestUrl =
+          'entry' in remote ? (remote as any).entry : undefined;
+        if (manifestUrl && origin.snapshotHandler?.manifestCache) {
+          const manifest =
+            origin.snapshotHandler.manifestCache.get(manifestUrl);
+          if (manifest) {
+            // Container bundle hash
+            const containerHash = (manifest.metaData?.buildInfo as any)?.hash;
+            if (containerHash && remoteInfo.entry) {
+              cacheLayer.registerBundleHash(remoteInfo.entry, containerHash);
+            }

-    const loadBundleAsync =
-      __loadBundleAsync as typeof globalThis.__loadBundleAsync;
+            // Exposed + shared bundle hashes
+            const hashes = extractBundleHashes(manifest, manifestUrl);
+            for (const [url, hash] of hashes) {
+              // Strip query params — loadBundle looks up hashes by bare URL
+              cacheLayer.registerBundleHash(url.split('?')[0], hash);
+            }

-    if (!loadBundleAsync) {
-      throw new Error('loadBundleAsync is not defined');
-    }
+            // Register manifest source for polling
+            cacheLayer.registerManifestSource(manifestUrl, extractBundleHashes);
+          }
+        }
+      } catch {
+        // non-critical — hash validation is best-effort
+      }
+      return args;
+    },


I think we could extract this to the cache package and make it a separate runtime plugin instead - do you think it's possible?

jbroma · 2026-03-31T18:21:17Z

packages/metro-core/src/modules/asyncRequire.ts

+    // For remote split bundles with cache enabled, convert relative paths to
+    // full URLs so they enter the same cache path as container bundles.
+    // In dev mode, getBundlePath returns relative paths unchanged, but we need
+    // full URLs for the cache layer (download + eval).
+    if (isSplitBundle && cacheLayer && publicPath && !isUrl(bundlePath)) {
+      bundlePath = joinComponents(publicPath, bundlePath);
+    }
+
+    // --- Cache layer: intercept bundles with full URLs (containers + remote split bundles) ---
+    if (cacheLayer && isUrl(bundlePath)) {
+      const { status } = await cacheLayer.loadBundle(bundlePath);
+      if (status === 'skipped') {
+        // Cache layer skipped — fall back to network load
+        const encodedBundlePath = bundlePath.replaceAll('../', '..%2F');
+        await loadBundleAsync(encodedBundlePath);
+      }
+      // else: 'cache-hit' or 'downloaded' — bundle already eval'd by cache layer
+    } else {
+      // No cache: host split bundles (no publicPath), cache disabled, or native-cache not installed
+      const encodedBundlePath = bundlePath.replaceAll('../', '..%2F');
+      await loadBundleAsync(encodedBundlePath);
+    }


This looks good but to me it feels out of place - with an optional layer we are introducing a lot of complexity into this module - do you think it would be possible to create wrapper around loadBundleAsync that introduces the cache layer and then load the MF wrapper?

I think we could rework the asyncRequire implementation, so that it would be possible to modify the actual loadBundleAsync and then add MF wrapper on top of it:

InitializeCore runs -> __loadBundleAsync gets initialized with default implementation

Cache wrapper runs -> enhances __loadBundleAsync with caching capabilities

MF metro-core wrapper runs -> adapts __loadBundleAsync to work with MF

This approach would most likely require splitting asyncRequire into two modules, something like this:

mf:init-async-require -> injects expo impl of async require if missing

mf:adapt-async-require -> adapts existing impl of async require to work with federation

in the cache plugin you could then modify the resolver for either of those to ensure module with cache wrapper runs after init and before adapt

mf:async-require, left over for compatibility could be then just:

import `mf:init-async-require`; import `mf:adapt-async-require`;

let me know what you think & if that makes sense to you

zhongwu and others added 12 commits March 16, 2026 13:03

feat(metro-cache): add native caching module for Metro bundles

f45cc37

chore(module-federation): revert unintended pre-commit and lockfile c…

032ce83

…hanges

feat(metro-cache): add JSI native bindings for file reading

56bfdb9

feat(metro-cache): refactor JSI installation to be JS-triggered synch…

03c26ae

…ronous

feat(metro-cache): simplify cache manager by removing MMKV dependency

3d42a82

chore(metro-cache): remove spec and bundle artifacts

bb44156

feat(metro-core): add inflight dedup for concurrent bundle loads

4cacb10

chore(metro-cache): remove MFE lifecycle management spec artifacts

99bbef2

feat(metro-cache): optimize native download and improve build configu…

beab9f2

…ration

feat(metro-core): refactor async bundle loading with cache integrity …

672aa0a

…verification

feat(metro-cache): add LRU cache eviction and file size tracking

29f62f8

chore(metro-cache): externalize Android dependency versions

1a85880

zhongwuzw added 13 commits March 21, 2026 23:20

refactor(metro-core): remove runtime cache module loader

cb103c8

feat(metro-cache): add BundleCacheLayer and enhance pre-download func…

03ace71

…tionality

refactor(metro-cache): rename CacheManagerConfig to MFECacheConfig an…

29cfd40

…d add register function

feat(metro-cache): add downloadUrlMap to preserve query params in pre…

95af437

…-download

refactor(metro-cache): replace downloadUrlMap with buildDownloadUrl c…

bd1dbe6

…allback

refactor(native-cache): rename metro-cache package to native-cache

978e6fb

refactor(metro-core): defer cache layer initialization in asyncRequire

e946c5e

fix(metro-core): disable cache layer forcing in dev mode

12cf08d

chore(native-cache): remove native cache package and integration

7369c0c

chore(metro-example-host): remove native-cache dependency

47dc009

refactor(metro-core): simplify cache layer interface and add type safety

b81e348

refactor(metro-core): simplify cache layer registration and enhance b…

8c40593

…undle URL resolution

refactor(metro-core): remove unnecessary preloading comment in asyncR…

b247277

…equire

zhongwuzw changed the title ~~[metro-cache] metro-cache preview~~ [metro-core] metro-core add cache Mar 26, 2026

zhongwuzw changed the title ~~[metro-core] metro-core add cache~~ (metro-core): add manifest SHA-256 hashes and optional bundle cache layer integration Mar 26, 2026

zhongwuzw mentioned this pull request Mar 26, 2026

feat(zephyr-native-cache): add native cache layer for React Native ZephyrCloudIO/zephyr-packages#412

Draft

5 tasks

jbroma reviewed Mar 31, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

(metro-core): add manifest SHA-256 hashes and optional bundle cache layer integration#4576

(metro-core): add manifest SHA-256 hashes and optional bundle cache layer integration#4576
zhongwuzw wants to merge 25 commits intomodule-federation:mainfrom
zhongwuzw:features/metro-cache

zhongwuzw commented Mar 20, 2026 •

edited

Loading

Uh oh!

netlify bot commented Mar 20, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 20, 2026 •

edited

Loading

Uh oh!

jbroma left a comment

Uh oh!

jbroma Mar 31, 2026

Uh oh!

jbroma Mar 31, 2026

Uh oh!

zhongwuzw Apr 1, 2026 •

edited

Loading

Uh oh!

jbroma Apr 2, 2026

Uh oh!

jbroma Mar 31, 2026

Uh oh!

zhongwuzw Apr 1, 2026

Uh oh!

jbroma Apr 2, 2026

Uh oh!

jbroma Mar 31, 2026

Uh oh!

jbroma Mar 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

zhongwuzw commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Types of changes

Checklist

Uh oh!

netlify bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for module-federation-docs ready!

Uh oh!

changeset-bot bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

jbroma left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zhongwuzw Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zhongwuzw commented Mar 20, 2026 •

edited

Loading

netlify bot commented Mar 20, 2026 •

edited

Loading

changeset-bot bot commented Mar 20, 2026 •

edited

Loading

zhongwuzw Apr 1, 2026 •

edited

Loading