@modern-js/app-tools 3.7.0 → 3.8.0

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

@@ -0,0 +1,118 @@
+# Server-Side Rendering
+
+`@module-federation/modern-js-v3` offers powerful capabilities, enabling developers to easily combine Module Federation with server-side rendering (SSR) in Modern.js applications.
+
+## Enable SSR
+
+Using the application created in [Using Module Federation](/guides/topic-detail/module-federation/usage.md) as an example, you only need to add the `server.ssr` configuration to both the producer and the consumer:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream',
+    },
+  },
+});
+```
+
+For better performance, we only support using this capability combination in Streaming SSR scenarios.
+
+:::warning
+Application-level modules (modules using `createBridgeComponent` and `createRemoteAppComponent`) do not support server-side rendering (SSR). If you need to use SSR functionality, please use component-level module export methods instead.
+:::
+
+## Data Fetching
+
+:::tip
+Currently, this feature is experimental and has not been fully practiced. Please use it with caution.
+:::
+
+Module Federation now supports [data fetching](https://module-federation.io/zh/guide/basic/data-fetch/index.html#%E7%AE%80%E4%BB%8B) capabilities. Each producer file can have a corresponding data fetching file, with the file name format of `[name].data.ts`.
+
+In Modern.js, data fetching can be used with SSR. Using the example in the previous chapter, create a data fetching file:
+
+```ts title="src/components/Button.data.ts"
+import type { DataFetchParams } from '@module-federation/modern-js-v3/react';
+
+export type Data = {
+  data: string;
+};
+
+export const fetchData = async (params: DataFetchParams): Promise<Data> => {
+  return new Promise(resolve => {
+    setTimeout(() => {
+      resolve({
+        data: `data: ${new Date()}`,
+      });
+    }, 1000);
+  });
+};
+```
+
+In Button, we get the data from the `Props`:
+
+```ts title="src/components/Button.tsx"
+import React from 'react';
+import type { Data } from './Button.data';
+
+export const Button = (props: { mfData: Data }) => {
+  const { mfData } = props;
+  return (
+    <button type="button" className="test">
+      Remote Button {mfData?.data}
+    </button>
+  );
+};
+```
+
+## Consuming Components
+
+Consumers must use [`createLazyComponent`](https://module-federation.io/practice/bridge/react-bridge/load-component.html#what-is-createlazycomponent) to load remote components and specify the export as the component name.
+
+```tsx title="src/routes/page.tsx"
+import type { JSX } from 'react';
+import { getInstance } from '@module-federation/modern-js-v3/runtime';
+import {
+  ERROR_TYPE,
+  lazyLoadComponentPlugin,
+} from '@module-federation/modern-js-v3/react';
+
+const instance = getInstance();
+instance!.registerPlugins([lazyLoadComponentPlugin()]);
+
+const Button = instance!.createLazyComponent({
+  loader: () => {
+    return import('remote/Button');
+  },
+  loading: 'loading...',
+  export: 'Button', // Configure this as the export name of the remote component
+  fallback: ({ error, errorType, dataFetchMapKey }) => {
+    console.error(error);
+    if (errorType === ERROR_TYPE.LOAD_REMOTE) {
+      return <div>load remote failed</div>;
+    }
+    if (errorType === ERROR_TYPE.DATA_FETCH) {
+      return (
+        <div>
+          data fetch failed, the dataFetchMapKey key is: {dataFetchMapKey}
+        </div>
+      );
+    }
+    return <div>error type is unknown</div>;
+  },
+});
+
+const Index = (): JSX.Element => {
+  return (
+    <div>
+      <h1>Basic usage with data fetch</h1>
+      <Button />
+    </div>
+  );
+};
+
+export default Index;
+```

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

@@ -0,0 +1,219 @@
+# Getting Started
+
+To use Module Federation in Modern.js, we recommend using the official plugin `@module-federation/modern-js-v3`.
+
+This section will introduce how to set up both producer and consumer applications using the official plugin. First, create two applications by following the [Modern.js Quick Start](/guides/get-started/quick-start.md).
+
+## Install the Plugin
+
+After creating the applications, install the plugin for both projects:
+
+
+```sh [npm]
+npm add @module-federation/modern-js-v3
+```
+
+```sh [yarn]
+yarn add @module-federation/modern-js-v3
+```
+
+```sh [pnpm]
+pnpm add @module-federation/modern-js-v3
+```
+
+```sh [bun]
+bun add @module-federation/modern-js-v3
+```
+
+```sh [deno]
+deno add npm:@module-federation/modern-js-v3
+```
+
+## Register the Plugin
+
+After installing the plugin, you need to register it in the `modern.config.js` file:
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
+
+export default defineConfig({
+  plugins: [appTools(), moduleFederationPlugin()],
+});
+```
+
+## Export Modules from Producer
+
+Next, modify the producer's code to export the Module Federation module.
+
+Create the `src/components/Button.tsx` file and export a Button component:
+
+```tsx title="src/components/Button.tsx"
+import React from 'react';
+
+export const Button = () => {
+  return <button type="button">Remote Button</button>;
+};
+```
+
+Then, add the `module-federation.config.ts` file at the project root to configure the Module Federation module's name, shared dependencies, and exports:
+
+```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: {
+    './Button': './src/components/Button.tsx',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+:::tip
+In the above code block, we have prefixed both the manifest and remoteEntry.js exported by Module Federation with `static`. This is because Modern.js requires all resources that need to be exposed to be placed in the `static/` directory, and Modern.js's server will only host the `static/` directory in production environments.
+:::
+
+Additionally, modify `modern.config.ts` to provide a development environment port for the producer, allowing the consumer to access the producer's resources through this port:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
+
+export default defineConfig({
+  server: {
+    port: 3051,
+  },
+  plugins: [appTools(), moduleFederationPlugin()],
+});
+```
+
+## Use Modules in Consumer
+
+Now, modify the consumer's code to use the module exported by the producer.
+
+Add the `module-federation.config.ts` file at the project root to configure the Module Federation module's name, shared dependencies, and the remote module to use:
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@http://localhost:3051/static/mf-manifest.json',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+`mf-manifest.json` is the file produced by the producer after packaging, containing all the information about the modules exported by the producer.
+
+Create a new route file `src/routes/remote/page.tsx` and import the producer module:
+
+```tsx title="src/routes/remote/page.tsx"
+import React, { Suspense, type JSX } from 'react';
+import { Button } from 'remote/Button';
+
+const Index = (): JSX.Element => {
+  return (
+    <div>
+      <Suspense fallback={<div>Loading...</div>}>
+        <Button />
+      </Suspense>
+    </div>
+  );
+};
+
+export default Index;
+```
+
+At this point, importing `remote/Button` will result in a type error because the local environment doesn't have the type for the remote module. Module Federation 2.0 provides [type hints](https://module-federation.io/zh/guide/basic/type-prompt.html), which will automatically generate type definitions for remote modules during the producer's build and download them during the consumer's build.
+
+To ensure the types take effect, add a new `path` in `tsconfig.json`:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      "*": ["./@mf-types/*"]
+    }
+  }
+}
+```
+
+:::tip
+In the consumer, we reference the remote module using `remote/Button`. Here's a brief explanation of what this path specifically represents. You can abstract it as `[remoteAlias]/[remoteExpose]`.
+
+The first part, `remoteAlias`, is the alias of the producer in the consumer. It is the `key` configured in the `remotes` field of the consumer's `module-federation.config.ts`:
+
+```ts
+{
+  remotes: {
+    [remoteAlias]: '[remoteModuleName]@[URL_ADDRESS]',
+  }
+}
+```
+
+Here, we also abstract the remote address as `[remoteModuleName]@[URL_ADDRESS]`. The part before `@` must correspond to the module name of the producer.
+
+The second part, `remoteExpose`, is the `key` configured in the `exposes` field of the producer's `module-federation.config.ts`.
+:::
+
+## Start the Applications
+
+Now, both the producer and consumer applications are set up. You can run `modern dev` locally to start both applications.
+
+Once started, the imports of the producer's modules in the consumer will no longer throw errors, and the types will be downloaded to the consumer application.
+
+:::note
+After modifying the producer's code, the consumer will automatically fetch the producer's types.
+:::
+
+Access `http://localhost:8080/remote`, and you will see that the page includes the `Button` component from the producer's remote module.
+
+We can also execute `modern serve` locally to simulate the production environment.
+
+Because the Module Federation plugin will automatically read Modern.js's `output.assetPrefix` configuration as the access address for remote modules, and this value defaults to `/` after building in the production environment.
+
+If we want to simulate the production environment in local, but not configure `output.assetPrefix`, consumers will pull the entry file of the remote module from their own domain. So We can add the following configuration:
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
+
+// https://modernjs.dev/en/configure/app/usage
+export default defineConfig({
+  server: {
+    port: 3051,
+  },
+  output: {
+    // Now this configuration is only used in the local when you run modern serve command.
+    // If you want to deploy the application to the platform, use your own domain name.
+    // Module federation will automatically write it to mf-manifest.json, which influences consumer to fetch remoteEntry.js.
+    assetPrefix: 'http://127.0.0.1:3051',
+  },
+  plugins: [appTools(), moduleFederationPlugin()],
+});
+```
+
+Now, in the producer, run `modern build && MODERN_MF_AUTO_CORS=true  modern serve`, and in the consumer, run `modern build && modern serve` to simulate the production environment locally and access the remote modules.
+
+:::tip
+When using the `modern serve` command, you need to set the `MODERN_MF_AUTO_CORS=true` environment variable when starting the producer project to automatically handle CORS issues and ensure that consumers can properly access the producer's remote module resources.
+:::
+
+You can refer to this example: [Modern.js & Module Federation Basic Example](https://github.com/web-infra-dev/modern.js/tree/main/examples/module-federation/base).
+
+## Related Documentation
+
+- [Module Federation Official Documentation](https://module-federation.io/zh/guide/framework/modernjs.html)

package/docs/guides/troubleshooting/builder.md

@@ -0,0 +1,110 @@
+# Build FAQ
+
+If you encounter any build-related issues, you can refer to the current document for troubleshooting.
+
+***
+
+### Rsbuild FAQ
+
+Modern.js is internally based on [Rsbuild](https://v2.rsbuild.rs/) and encapsulates its own build tool, so you can directly refer to the FAQ document of Rsbuild:
+
+- [Rsbuild - Features FAQ](https://v2.rsbuild.rs/guide/faq/features)
+- [Rsbuild - Exceptions FAQ](https://v2.rsbuild.rs/guide/faq/exceptions)
+- [Rsbuild - HMR FAQ](https://v2.rsbuild.rs/guide/faq/hmr)
+
+***
+
+### How to view the final generated Rspack configuration?
+
+Modern.js provides [inspect command](https://modernjs.dev/en/apis/app/commands.html) to view the final Modern.js configuration and Rspack configuration generated by the project.
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Builder Config: /root/my-project/dist/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+```
+
+***
+
+### Failed import other modules in Monorepo?
+
+Due to considerations of compilation performance, by default, the Modern.js does not compile files under `node_modules` or files outside the current project directory.
+
+Therefore, when you reference the source code of other sub-projects, you may encounter an error similar to `You may need an additional loader to handle the result of these loaders.`
+
+There are several solutions to this problem:
+
+1. You can enable the source code build mode to compile other sub-projects within the monorepo. Please refer to [Source Code Build Mode](/guides/advanced-features/source-build.md) for more information.
+2. You can add the `source.include` configuration option to specify the directories or modules that need to be additionally compiled. Please refer to [Usage of source.include](/configure/app/source/include.md) for more information.
+3. You can pre-build the sub-projects that need to be referenced, generate the corresponding build artifacts, and then reference the build artifacts in the current project instead of referencing the source code.
+
+***
+
+### Find `exports is not defined` runtime error?
+
+If the compilation is succeed, but the `exports is not defined` error appears after opening the page, it is usually because a CommonJS module is compiled by Babel.
+
+Under normal circumstances, Modern.js will not use Babel to compile CommonJS modules. If the [source.include](/configure/app/source/include.md) configuration option is used in the project, some CommonJS modules may be added to the Babel compilation.
+
+There are two workarounds for this problem:
+
+1. Avoid adding CommonJS modules to Babel compilation.
+2. Set Babel's `sourceType` configuration to `unambiguous`.
+
+***
+
+### Compile error "Error: ES Modules may not assign module.exports or exports.\*, Use ESM export syntax"?
+
+If the following error occurs during compilation, it is usually because a CommonJS module is compiled with Babel in the project, and the solution is same as the above `exports is not defined` problem.
+
+```bash
+Error: ES Modules may not assign module.exports or exports.*, Use ESM export syntax, instead: 581
+```
+
+For more information, please refer to issue: [babel#12731](https://github.com/babel/babel/issues/12731).
+
+***
+
+### The compilation progress bar is stuck, but there is no Error log in the terminal?
+
+When the compilation progress bar is stuck, but there is no Error log on the terminal, it is usually because an exception occurred during the compilation. In some cases, when Error is caught by the build tool or other modules, the error log can not be output correctly. The most common scenario is that there is an exception in the Babel config, which is caught by the build tool, and the build tool swallows the Error in some cases.
+
+**Solution:**
+
+If this problem occurs after you modify the Babel config, it is recommended to check for the following incorrect usages:
+
+1. You have configured a plugin or preset that does not exist, maybe the name is misspelled, or it is not installed correctly.
+2. Whether multiple babel-plugin-imports are configured, but the name of each babel-plugin-import is not declared in the third item of the array.
+
+***
+
+### Compilation error after referencing a type from lodash
+
+If the `@types/lodash` package is installed in your project, you may import some types from `lodash`, such as the `DebouncedFunc` type:
+
+```ts
+import { debounce, DebouncedFunc } from 'lodash';
+```
+
+Modern.js will throw an error after compiling the above code:
+
+```bash
+Syntax error: /project/src/index.ts: The lodash method `DebouncedFunc` is not a known module.
+Please report bugs to https://github.com/lodash/babel-plugin-lodash/issues.
+```
+
+The reason is that Modern.js has enabled the [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash) plugin by default to optimize the bundle size of lodash, but Babel cannot distinguish between "value" and "type", which resulting in an exception in the compiled code.
+
+The solution is to use TypeScript's `import type` syntax to explicitly declare the `DebouncedFunc` type:
+
+```ts
+import { debounce } from 'lodash';
+import type { DebouncedFunc } from 'lodash';
+```
+
+:::tip
+In any case, it is recommended to use `import type` to import types, this will help the compiler to identify the type.
+:::

package/docs/guides/troubleshooting/cli.md

@@ -0,0 +1,35 @@
+# CLI FAQ
+
+### Unable to pass command line arguments correctly when using pnpm?
+
+When using pnpm to call the commands in `package.json`, you need to pay attention to how parameters are passed:
+
+- **If you need to pass parameters to pnpm**, you need to put the parameters before the command.
+
+For example, using the pnpm `--filter` parameter to run the prepare command:
+
+```bash
+pnpm run --filter "./packages/**" prepare
+```
+
+- **If you need to pass parameters to the command**, you need to put the parameters after the command.
+
+For example, in the following `package.json` configuration:
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+The way to pass parameters when running the command is:
+
+```bash
+pnpm run command --options
+```
+
+:::tip
+Modern.js requires Node.js >= 20.19.5, and pnpm v6 does not support Node.js 20, so please use pnpm v7 or higher.
+:::

package/docs/guides/troubleshooting/dependencies.md

@@ -0,0 +1,119 @@
+# Dependencies FAQ
+
+### How to check the actual installed version of a dependency in the project?
+
+You can use the `ls` command provided by the package manager to view the version of the dependency in the project.
+
+Here are some basic examples. For detailed usage, please refer to the documentation of each package manager.
+
+**npm / yarn**
+
+For projects using npm or yarn, you can use the `npm ls` command.
+
+For example, running `npm ls @modern-js/plugin` will show the following result:
+
+```
+project
+└─┬ @modern-js/app-tools@x.y.z
+  └── @modern-js/plugin@x.y.z
+```
+
+**pnpm**
+
+For projects using pnpm, you can use the `pnpm ls` command.
+
+For example, running `pnpm ls @modern-js/plugin --depth Infinity` will show the following result:
+
+```
+devDependencies:
+@modern-js/app-tools x.y.z
+└── @modern-js/plugin x.y.z
+```
+
+***
+
+### Getting "The engine "node" is incompatible" error during dependency installation?
+
+If you encounter the following error message during dependency installation, it means that the current environment is using a Node.js version that is too low, and you need to upgrade Node.js to a higher version.
+
+```bash
+The engine "node" is incompatible with this module.
+
+Expected version ">=20.19.5". Got "16.20.1"
+```
+
+Modern.js requires Node.js version >= 20.19.5. We strongly recommend using the latest LTS version (such as [Node.js 22 LTS](https://nodejs.org/)) for the best experience.
+
+If the Node.js version of the current environment is lower than the above requirement, you can use tools such as [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to switch versions.
+
+Here is an example of using nvm:
+
+```bash
+# Install Node.js 22 LTS
+nvm install 22 --lts
+
+# Switch to Node.js 22
+nvm use 22
+
+# Set Node.js 22 as the default version
+nvm alias default 22
+```
+
+For local development environments, it is recommended to use [fnm](https://github.com/Schniz/fnm), which has better performance than nvm and has similar usage.
+
+***
+
+### Getting a ReactNode type error after upgrading dependencies?
+
+After upgrading the dependencies of the project, if the following type error occurs, it means that the wrong version of `@types/react` is installed in the project.
+
+```bash
+The types returned by 'render()' are incompatible between these types.
+Type 'React.ReactNode' is not assignable to type 'import("/node_modules/@types/react/index").ReactNode'.
+Type '{}' is not assignable to type 'ReactNode'.
+```
+
+The reason for this problem is that the ReactNode type definition in React 18/19 is different from that in React 16/17. If there are multiple different versions of `@types/react` in the project, a ReactNode type conflict will occur, resulting in the above error.
+
+The solution is to lock the `@types/react` and `@types/react-dom` in the project to a unified version, such as `v17`.
+
+```json
+{
+  "@types/react": "^19",
+  "@types/react-dom": "^19"
+}
+```
+
+For methods of locking dependency versions, please refer to [Lock nested dependency](/guides/get-started/upgrade.md#lock-nested-dependency).
+
+***
+
+### Getting peer dependencies warnings in the console after running `pnpm install`?
+
+The reason for this warning is that the version range of peer dependencies declared by some third-party npm packages is inconsistent with the version range installed in Modern.js.
+
+In most cases, peer dependencies warnings will not affect the project operation and do not need to be processed separately. Please ignore the relevant warnings.
+
+***
+
+### What is the minimum supported version of React for the Modern.js framework?
+
+**Modern.js framework requires React version >= 18.0.0**.
+
+- **If you are using Modern.js runtime capabilities** (including SSR, Streaming SSR, data loading, routing, etc.), you must use React 18 or higher. React 16 and React 17 are no longer supported.
+- **If you are only using Modern.js build capabilities** (without runtime), React 16 or React 17 may theoretically work, but it is strongly recommended to upgrade to React 18 or higher for the best experience and full feature support.
+
+***
+
+### Type error in Modern.js configuration file?
+
+```bash
+Type 'CliPlugin<{}, {}, {}, {}>' is not assignable to type 'CliPlugin<any, {}, {}, {}>'.
+  Types of property 'setup' are incompatible.
+```
+
+When you use the Modern.js framework, the above error occurs in the configuration file, it may be due to the inconsistent versions of Modern.js related packages. You need to manually update all `@modern-js/**` packages to the same version.
+
+In the monorepo, the above error may also occur due to inconsistent versions of the Modern.js framework used by different sub-projects.
+
+For information on how to unify and upgrade dependency versions, please refer to the [Upgrading](/guides/get-started/upgrade.md) documentation.