feat(runtime): observe preload resource results

[2heal1]

Description

Add resource-level observability for preloadRemote and document how to consume the result.

This change makes preload flows easier to inspect:

• preloadRemote now waits for the resource results of the current preload call.
• Resource results include success, error, timeout, and cached states.
• Resource loading hooks receive context that identifies whether the request came from loadRemote or preloadRemote.
• The observability plugin records preload results in reports.
• Runtime API docs include examples for checking preload success/failure and reading failed resources.

Usage Example

Reviewers can use the new behavior directly from the preloadRemote Promise:

import { preloadRemote } from '@module-federation/enhanced/runtime';

preloadRemote([
  {
    nameOrAlias: 'provider',
    exposes: ['Button'],
    resourceCategory: 'all',
  },
])
  .then(() => {
    console.log('provider/Button preload completed');
  })
  .catch((error) => {
    const failedResources =
      error.failedResults ??
      error.results
        ?.flatMap((remoteResult) => remoteResult.results)
        .filter(
          (resource) =>
            resource.status === 'error' || resource.status === 'timeout',
        );

    console.error('provider/Button preload failed', failedResources);
  });

Runtime plugins can also use resourceContext to apply different resource policies:

const resourcePolicyPlugin = () => ({
  name: 'resource-policy-plugin',
  createScript({ resourceContext }) {
    if (resourceContext?.initiator === 'loadRemote') {
      return { timeout: 30000 };
    }
  },
  createLink({ resourceContext }) {
    if (resourceContext?.initiator === 'preloadRemote') {
      return { timeout: 5000 };
    }
  },
});

Related Issue

N/A

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.

Validation:

• pnpm --filter @module-federation/runtime-core exec tsc --noEmit --pretty false
• pnpm --filter @module-federation/observability-plugin exec tsc --noEmit --pretty false
• pnpm --filter @module-federation/sdk exec tsc --noEmit --pretty false
• pnpm --filter @module-federation/runtime-core test -- hooks.spec.ts
• pnpm --filter @module-federation/observability-plugin test -- observability.spec.ts
• pnpm exec prettier --check <changed files>
• git diff --check

The commit hook also ran Prettier and package lint for the changed runtime, SDK, and observability packages.

[changeset-bot]

🦋 Changeset detected

Latest commit: 22a9327

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 46 packages

Name	Type
@module-federation/runtime-core	Patch
@module-federation/observability-plugin	Patch
@module-federation/sdk	Patch
@module-federation/runtime	Patch
@module-federation/bridge-react	Patch
@module-federation/devtools	Patch
@module-federation/cli	Patch
@module-federation/dts-plugin	Patch
@module-federation/enhanced	Patch
@module-federation/esbuild	Patch
@module-federation/managers	Patch
@module-federation/manifest	Patch
@module-federation/metro	Patch
@module-federation/modern-js-v3	Patch
@module-federation/modern-js	Patch
@module-federation/nextjs-mf	Patch
@module-federation/node	Patch
@module-federation/retry-plugin	Patch
@module-federation/rsbuild-plugin	Patch
@module-federation/rspack	Patch
@module-federation/rspress-plugin	Patch
@module-federation/storybook-addon	Patch
@module-federation/utilities	Patch
@module-federation/webpack-bundler-runtime	Patch
@module-federation/bridge-react-webpack-plugin	Patch
@module-federation/bridge-vue3	Patch
@module-federation/runtime-tools	Patch
shared-tree-shaking-no-server-host	Patch
shared-tree-shaking-no-server-provider	Patch
@module-federation/metro-plugin-rnc-cli	Patch
@module-federation/metro-plugin-rnef	Patch
@module-federation/metro-plugin-rock	Patch
shared-tree-shaking-with-server-host	Patch
shared-tree-shaking-with-server-provider	Patch
node-dynamic-remote-new-version	Patch
node-dynamic-remote	Patch
remote5	Patch
remote6	Patch
website-new	Patch
@module-federation/inject-external-runtime-core-plugin	Patch
@module-federation/third-party-dts-extractor	Patch
@module-federation/bridge-shared	Patch
@module-federation/error-codes	Patch
create-module-federation	Patch
@module-federation/treeshake-server	Patch
@module-federation/treeshake-frontend	Patch

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

Open in StackBlitz

@module-federation/devtools

pnpm add https://pkg.pr.new/@module-federation/devtools@22a9327

@module-federation/cli

pnpm add https://pkg.pr.new/@module-federation/cli@22a9327

create-module-federation

pnpm add https://pkg.pr.new/create-module-federation@22a9327

@module-federation/dts-plugin

pnpm add https://pkg.pr.new/@module-federation/dts-plugin@22a9327

@module-federation/enhanced

pnpm add https://pkg.pr.new/@module-federation/enhanced@22a9327

@module-federation/error-codes

pnpm add https://pkg.pr.new/@module-federation/error-codes@22a9327

@module-federation/esbuild

pnpm add https://pkg.pr.new/@module-federation/esbuild@22a9327

@module-federation/managers

pnpm add https://pkg.pr.new/@module-federation/managers@22a9327

@module-federation/manifest

pnpm add https://pkg.pr.new/@module-federation/manifest@22a9327

@module-federation/metro

pnpm add https://pkg.pr.new/@module-federation/metro@22a9327

@module-federation/metro-plugin-rnc-cli

pnpm add https://pkg.pr.new/@module-federation/metro-plugin-rnc-cli@22a9327

@module-federation/metro-plugin-rnef

pnpm add https://pkg.pr.new/@module-federation/metro-plugin-rnef@22a9327

@module-federation/metro-plugin-rock

pnpm add https://pkg.pr.new/@module-federation/metro-plugin-rock@22a9327

@module-federation/modern-js

pnpm add https://pkg.pr.new/@module-federation/modern-js@22a9327

@module-federation/modern-js-v3

pnpm add https://pkg.pr.new/@module-federation/modern-js-v3@22a9327

@module-federation/native-federation-tests

pnpm add https://pkg.pr.new/@module-federation/native-federation-tests@22a9327

@module-federation/native-federation-typescript

pnpm add https://pkg.pr.new/@module-federation/native-federation-typescript@22a9327

@module-federation/nextjs-mf

pnpm add https://pkg.pr.new/@module-federation/nextjs-mf@22a9327

@module-federation/node

pnpm add https://pkg.pr.new/@module-federation/node@22a9327

@module-federation/observability-plugin

pnpm add https://pkg.pr.new/@module-federation/observability-plugin@22a9327

@module-federation/retry-plugin

pnpm add https://pkg.pr.new/@module-federation/retry-plugin@22a9327

@module-federation/rsbuild-plugin

pnpm add https://pkg.pr.new/@module-federation/rsbuild-plugin@22a9327

@module-federation/rspack

pnpm add https://pkg.pr.new/@module-federation/rspack@22a9327

@module-federation/rspress-plugin

pnpm add https://pkg.pr.new/@module-federation/rspress-plugin@22a9327

@module-federation/runtime

pnpm add https://pkg.pr.new/@module-federation/runtime@22a9327

@module-federation/runtime-core

pnpm add https://pkg.pr.new/@module-federation/runtime-core@22a9327

@module-federation/runtime-tools

pnpm add https://pkg.pr.new/@module-federation/runtime-tools@22a9327

@module-federation/sdk

pnpm add https://pkg.pr.new/@module-federation/sdk@22a9327

@module-federation/storybook-addon

pnpm add https://pkg.pr.new/@module-federation/storybook-addon@22a9327

@module-federation/third-party-dts-extractor

pnpm add https://pkg.pr.new/@module-federation/third-party-dts-extractor@22a9327

@module-federation/treeshake-frontend

pnpm add https://pkg.pr.new/@module-federation/treeshake-frontend@22a9327

@module-federation/treeshake-server

pnpm add https://pkg.pr.new/@module-federation/treeshake-server@22a9327

@module-federation/typescript

pnpm add https://pkg.pr.new/@module-federation/typescript@22a9327

@module-federation/utilities

pnpm add https://pkg.pr.new/@module-federation/utilities@22a9327

@module-federation/webpack-bundler-runtime

pnpm add https://pkg.pr.new/@module-federation/webpack-bundler-runtime@22a9327

@module-federation/bridge-react

pnpm add https://pkg.pr.new/@module-federation/bridge-react@22a9327

@module-federation/bridge-react-webpack-plugin

pnpm add https://pkg.pr.new/@module-federation/bridge-react-webpack-plugin@22a9327

@module-federation/bridge-shared

pnpm add https://pkg.pr.new/@module-federation/bridge-shared@22a9327

@module-federation/bridge-vue3

pnpm add https://pkg.pr.new/@module-federation/bridge-vue3@22a9327

@module-federation/inject-external-runtime-core-plugin

pnpm add https://pkg.pr.new/@module-federation/inject-external-runtime-core-plugin@22a9327

commit: 22a9327

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 08c71a66be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Correct preloadRemote promise semantics

This new contract is inconsistent with the runtime implementation: preloadRemote does not wait for CSS/JS preload completion and does not surface per-resource failure results. In packages/runtime-core/src/remote/index.ts it only awaits snapshot/asset generation and then calls preloadAssets(...); preloadAssets (packages/runtime-core/src/utils/preload.ts) appends <link>/<script> tags with no awaited success/error path, and no code path populates an error.results structure like the example. As written, consumers may incorrectly treat await preloadRemote(...) as a reliable success/failure gate and build retry/error handling that never receives the documented resource-level statuses.

Useful? React with 👍 / 👎.