@modern-js/app-tools 3.6.0 → 3.8.0

package/docs/guides/topic-detail/module-federation/application.md

@@ -0,0 +1,116 @@
+# Application-Level Modules
+
+Modern.js provides runtime APIs to quickly export application-level Module Federation modules from your application.
+
+We use the application created in [Using Module Federation](/guides/topic-detail/module-federation/usage.md) as an example to further explain how to import application-level modules.
+
+## Exporting Modules from Producer
+
+Unlike directly exporting component-level modules, we need to create a separate entry for application-level modules to be exported via `Module Federation`.
+
+We create the `src/export-App.tsx` file:
+
+:::note
+The filename can be arbitrary; Modern.js does not enforce a specific naming convention.
+:::
+
+```ts title="src/export-App.tsx"
+import '@modern-js/runtime/registry/index'; // This line must be included, it will import micro frontend runtime dependencies by default
+import { render } from '@modern-js/runtime/browser';
+import { createRoot } from '@modern-js/runtime/react';
+import { createBridgeComponent } from '@module-federation/modern-js-v3/react-v19';
+
+const ModernRoot = createRoot();
+export const provider = createBridgeComponent({
+  rootComponent: ModernRoot,
+  render: (Component, dom) => render(Component, dom),
+});
+
+export default provider;
+```
+
+:::note
+Please select the corresponding import path based on the React version used in your project:
+
+- **React 19**: Use `@module-federation/modern-js-v3/react-v19`
+- **React 18**: Use `@module-federation/modern-js-v3/react-v18`
+
+You can check the React version in your project's `package.json` file to determine which import path to use.
+:::
+
+This file will pass the root component of the `main` entry application to the Bridge API and render it to the specified node via Bridge's render function.
+
+Next, we configure `module-federation.config.ts` to modify the export to `src/export-App.tsx`:
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'remote',
+  manifest: {
+    filePath: 'static',
+  },
+  filename: 'static/remoteEntry.js',
+  exposes: {
+    './app': './src/export-App.tsx',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+:::info
+[`createBridgeComponent`](https://module-federation.io/guide/bridge/overview#core-apis) is used to export application-level modules. Modern.js related APIs can be found at [createRoot](/apis/app/runtime/core/create-root.md) and [render](/apis/app/runtime/core/render.md).
+:::
+
+## Using Modules in Consumer
+
+We then modify the consumer configuration by removing the previously created `src/routes/remote/page.tsx` route file.
+
+We want all routes that access `/remote` to enter the aforementioned application-level module, so we add `src/routes/remote/$.tsx` instead.
+
+:::note
+If you are not familiar with the capabilities of `$.tsx`, please read [Wildcard Routes](/guides/basic-features/routes/routes.md#wildcard-routes).
+:::
+
+```tsx title="src/routes/remote/$.tsx"
+import { createRemoteAppComponent } from '@module-federation/modern-js-v3/react';
+import { loadRemote } from '@module-federation/modern-js-v3/runtime';
+
+const ErrorBoundary = (info?: { error: { message: string } }) => {
+  return (
+    <div>
+      <h2>This is ErrorBoundary Component, Something went wrong:</h2>
+      <pre style={{ color: 'red' }}>{info?.error.message}</pre>
+    </div>
+  );
+};
+const Loading = <div>loading...</div>;
+const RemoteApp = createRemoteAppComponent({
+  loader: () => loadRemote('remote/app'),
+  fallback: ErrorBoundary,
+  loading: Loading,
+});
+
+export default RemoteApp;
+```
+
+:::info
+[`createRemoteAppComponent`](https://module-federation.io/guide/bridge/overview#core-apis) is used to load application-level modules.
+:::
+
+## Start the Application
+
+Now, both the producer and consumer applications are set up. We can run `modern dev` locally to start both applications.
+
+After startup, when the consumer application accesses the `/remote` route, it will enter the producer application. Accessing `http://localhost:8080/remote` will display a complete page of the producer's remote module in the browser.
+
+You can create new route files in the producer application and add route navigation in the code. These functionalities will also work as expected.
+
+You can refer to the example here: [Modern.js & Module Federation Application-Level Modules](https://github.com/web-infra-dev/modern.js/tree/main/examples/module-federation/app-export).
+
+## Related Documentation
+
+- [Module Federation Bridge](https://module-federation.io/guide/bridge/overview)

package/docs/guides/topic-detail/module-federation/deploy.md

@@ -0,0 +1,104 @@
+# Deployment
+
+In general, when deploying a Module Federation application, there are two key points to consider:
+
+1. Ensure that the remote module addresses in the consumer's configuration file are correct, and that the consumer can correctly access the producer's `manifest` file.
+2. Ensure that all resources in the producer's `manifest` file can be accessed correctly.
+
+We recommend using Modern.js's [Node Server](/guides/basic-features/deploy.md#using-modernjs-built-in-nodejs-server) to deploy Module Federation applications for an out-of-the-box experience.
+
+## Consumer
+
+For the consumer of Module Federation, its connection with the producer is the remote module address in the configuration file.
+
+For example, if the producer is deployed under the domain `https://my-remote-module`, the developer needs to modify the consumer's configuration file:
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@https://my-remote-module/static/mf-manifest.json',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+At this point, the consumer will load the `manifest` configuration file of the remote module production environment.
+
+:::note
+In the above code, the address of the remote module is `/static/mf-manifest.json`, which is just an example using the default output path of Modern.js. In actual projects, developers need to configure according to the actual access path.
+:::
+
+## Producer
+
+For the producer of Module Federation, developers need to correctly configure the [`output.assetPrefix`](/configure/app/output/asset-prefix.md) configuration, which affects:
+
+1. The `publicPath` defined in `mf-manifest.json`, which determines the access path of other resources of the remote module.
+2. The access path of the `mf-manifest.json` file when hosted directly by the Modern.js server.
+
+In the production environment, developers need to configure `output.assetPrefix` as the access path of the production environment. For example, if we deploy the producer under the domain `https://my-remote-module`, we need to configure `output.assetPrefix` as `https://my-remote-module`.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  output: {
+    assetPrefix: 'https://my-remote-module',
+  },
+});
+```
+
+At this point, the `publicPath` defined in the producer's build output `mf-manifest.json` is `https://my-remote-module`, for example:
+
+```json
+{
+  "id": "remote",
+  "name": "remote",
+  "metaData": {
+    "name": "remote",
+    "publicPath": "https://my-remote-module/"
+  },
+  "shared": [ /* xxx */ ],
+  "remotes": [],
+  "exposes": [ /* xxx */ ]
+}
+```
+
+When the consumer accesses the remote module, it will automatically prepend the `publicPath` to the resource path of the remote module.
+
+This configuration will also affect the access path of the producer's `mf-manifest.json`. For example, if this value is set to `MyDomain/module-a`, the hosting path of `mf-manifest.json` becomes `MyDomain/module-a/static/mf-manifest.json`.
+
+At this point, the consumer needs to configure the following address when configuring the remote module:
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@MyDomain/module-a/static/mf-manifest.json',
+  },
+});
+```
+
+## Local Deployment Verification
+
+Modern.js provides the `modern deploy` command, which can easily generate products that can run in a Node.js environment.
+
+```bash
+modern deploy
+```
+
+After executing the command, you can see the following output in the console:
+
+```bash
+Static directory: .output/static
+You can preview this build by node .output/index
+```
+
+At this point, the developer only needs to run `node .output/index` to preview the effect locally. Whether it is a CSR or an SSR application, all Module Federation files can be accessed correctly.