@modern-js/app-tools 3.7.0 → 3.8.0

package/docs/configure/app/source/decorators.md

@@ -0,0 +1,25 @@
+# source.decorators
+
+- **Type:**
+
+```ts
+type Decorators = {
+  version?: 'legacy' | '2022-03';
+};
+```
+
+- **Default:**
+
+```ts
+const defaultDecorators = {
+  version: 'legacy';
+};
+```
+
+Used to configure the decorators syntax.
+
+:::warning
+The usage of this configuration item is exactly the same as that of Rsbuild, but the default value is different. For detailed information, please refer to [Rsbuild - source.decorators](https://v2.rsbuild.rs/config/source/decorators).
+:::
+
+We found that most projects still use the `legacy` version of the decorator syntax, so the default value is `legacy`.

package/docs/configure/app/source/define.md

@@ -0,0 +1,16 @@
+# source.define
+
+- **Type:** `Record<string, unknown>`
+- **Default:**
+
+```ts
+const defaultDefine = {
+  'process.env.MODERN_TARGET': '"browser"',
+};
+```
+
+Replaces variables in your code with other values or expressions at compile time. This can be useful for allowing different behavior between development builds and production builds.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - source.define](https://v2.rsbuild.dev/config/source/define).
+:::

package/docs/configure/app/source/disable-default-entries.md

@@ -0,0 +1,28 @@
+# source.disableDefaultEntries
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Used to disable the functionality of automatically identifying page entry points based on directory structure.
+
+:::info
+By default, Modern.js automatically determines the entry points of pages based on directory conventions, as described in [Entries](/guides/concept/entries.md).
+
+:::
+
+To disable this default behavior, set the following:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableDefaultEntries: true,
+  },
+});
+```
+
+After disabling the default behavior, you will need to use the [`source.entries`](/configure/app/source/entries.md) configuration to define custom entry points.
+
+:::warning
+We recommend organizing your code using the directory conventions provided by Modern.js to make better use of the framework's functionality and to avoid some redundant configurations.
+
+:::

package/docs/configure/app/source/enable-async-entry.md

@@ -0,0 +1,54 @@
+# source.enableAsyncEntry
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+This option is used for Rspack Module Federation scenario.
+
+When this option is enabled, Modern.js will wrap the automatically generated entry files with dynamic import (Asynchronous Boundaries), allowing page code to consume remote modules generated by Module Federation.
+
+## Background
+
+Module Federation (MF) is a technology solution that allows multiple JavaScript applications to share code and resources. Similar to microservices architecture on the server side, it allows you to split large applications into multiple independent smaller applications that can be developed, tested, and deployed independently, while dynamically loading modules from other applications at runtime.
+
+Module Federation solves the problem of code duplication across multiple frontend applications. In the traditional approach, if multiple applications need to use the same components or utility functions, you would need to duplicate this code in each application, leading to code duplication, high maintenance costs, and larger application sizes. With Module Federation, you can place common code in one application and have other applications load it dynamically as needed, enabling code sharing and reducing duplication.
+
+Module Federation 2.0 supports [Rspack](https://rspack.rs/) build tools, and provides enhanced features such as dynamic type hints, Manifest, Federation Runtime, runtime plugin system, and Chrome Devtools support for better development experience and debugging capabilities. You can visit the [Module Federation official documentation](https://module-federation.io/) to learn more.
+
+Modern.js provides an example project for Module Federation. Please refer to [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs).
+
+## Example
+
+First, enable this option in the configuration file:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+  },
+});
+```
+
+Then run the `dev` or `build` command, and you will see that the files automatically generated by Modern.js have the following structure:
+
+```bash
+node_modules
+  └─ .modern-js
+     └─ main
+        ├─ bootstrap.jsx  # asynchronous entry file
+        ├─ index.js      # real entry code
+        └─ index.html
+```
+
+The contents of `bootstrap.js` are as follows:
+
+```js
+import('./index.jsx');
+```
+
+At this point, you can consume any remote module in the current page.
+
+:::info
+Modern.js does not have ModuleFederationPlugin plugin built in. Please configure the ModuleFederationPlugin yourself via [tools.bundlerChain](/configure/app/tools/bundler-chain.md).
+
+:::

package/docs/configure/app/source/enable-async-pre-entry.md

@@ -0,0 +1,26 @@
+# source.enableAsyncPreEntry
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+When enabled, Modern.js will inject the modules configured in `source.preEntry` to the top of the auto-generated entry file (`index.jsx`) in order.
+
+This option only takes effect when `source.enableAsyncEntry` is enabled. If async entry is not enabled, this behavior will be skipped and the original builder-side `source.preEntry` injection remains unchanged.
+
+This option is mainly designed to work with `source.enableAsyncEntry`: when async entry is enabled, the final build entry becomes `bootstrap.jsx`, and the builder-side `source.preEntry` may not be injected into the real entry code. With `source.enableAsyncPreEntry` enabled, `preEntry` will be injected into `index.jsx` (the real entry code), so it also works in async entry scenarios.
+
+Meanwhile, when both `source.enableAsyncEntry` and `source.enableAsyncPreEntry` are enabled, Modern.js will not pass `source.preEntry` into builder config to avoid duplicate injection or injection into an unexpected entry.
+
+## Example
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre-a.ts', './src/pre-b.ts'],
+  },
+});
+```

package/docs/configure/app/source/entries-dir.md

@@ -0,0 +1,35 @@
+# source.entriesDir
+
+- **Type:** `string`
+- **Default:** `'./src'`
+
+By default, Modern.js scans the `src` directory to identify page entries. You can customize the directory used for identifying page entries with this option.
+
+For example, with the following configuration and directory structure:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entriesDir: './src/pages',
+  },
+});
+```
+
+```bash title="Project directory structure"
+.
+└── src
+    └── pages
+        ├── a
+        │   └── App.tsx
+        └── b
+            └── App.tsx
+```
+
+Modern.js will generate the build entries `a` and `b` based on the `./src/pages` directory structure. The result is as follows:
+
+```js
+const entry = {
+  a: './src/pages/a/App.tsx',
+  b: './src/pages/b/App.tsx',
+};
+```

package/docs/configure/app/source/entries.md

@@ -0,0 +1,179 @@
+# source.entries
+
+- **Type:**
+
+```ts
+type Entries = Record<
+  string,
+  | string
+  | {
+      entry: string;
+      disableMount?: boolean;
+    }
+>;
+```
+
+- **Default:** The entry object calculated based on the directory structure of the current project.
+
+Used to configure custom page entries.
+
+:::tip When to use
+For most scenarios, the entry automatically generated by Modern.js based on the directory structure can meet the requirements. For details, please refer to [Entry](/guides/concept/entries.md).
+
+If you need to customize page entries, you can set them through this option.
+
+:::
+
+## String
+
+When the value of the `entries` object is of type `string`, it represents the file path of the entry module:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      // Specify a new entry named 'my-entry'
+      'my-entry': './src/home/test/index.ts',
+    },
+    disableDefaultEntries: true,
+  },
+});
+```
+
+By default, the configured entry is equivalent to `App.tsx`, which means that the specified entry file **only needs to export the root component of the application**.
+
+For example, the following directory structure:
+
+```bash
+.
+├── src
+│   └── entry
+│       ├── chat.tsx
+│       └── home.tsx
+└── package.json
+```
+
+The above directory does not conform to the directory structure convention of Modern.js, so Modern.js will not get any default entries when analyzing the directory structure.
+
+If you do not want to change the directory structure (such as project migration), you can customize the entry through `source.entries`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      home: './src/entry/home.tsx',
+      chat: './src/entry/chat.tsx',
+    },
+    disableDefaultEntries: true,
+  },
+});
+```
+
+## Object
+
+When the value is `Object`, the following attributes can be configured:
+
+- `entry`: `string`, the entry file path.
+- `disableMount`: `boolean = false`, disable Modern.js's behavior of automatically generating entry code.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      'my-entry': {
+        // entry file path
+        entry: './src/my-page/index.tsx',
+        disableMount: true,
+      },
+    },
+    // Disable default entry scanning
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### Disable entry file generation
+
+By default, the configured entry is equivalent to `App.tsx`, and Modern.js will automatically generate an entry file to reference the entry you configured.
+
+If you want to disable the logic of Modern.js automatically generating entry files, you can set the `disableMount` property to `true`.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      'my-entry': {
+        entry: './src/my-page/index.tsx',
+        disableMount: true,
+      },
+    },
+    // Disable default entry scanning
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### Conventional Routing
+
+If you need to enable conventional routing for a custom entry, you can set `entry` to a directory path:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      // enable conventional routing
+      entry_spa: {
+        // The entry path of conventional routing must be set to a directory
+        entry: './src/about',
+      },
+    },
+    // Disable default entry scanning
+    disableDefaultEntries: true,
+  },
+});
+```
+
+## Entry Merge Rules
+
+After setting `source.entries`, if `disableDefaultEntries: true` is not set, Modern.js will merge the custom entry with the entry obtained by analyzing the directory structure.
+
+The merge rule is:
+
+- Compare the entry paths set by the custom entry setting and the default entry path. When the entry paths are the same, the custom entry will override the default entry.
+
+For example, the following directory structure:
+
+```bash
+.
+├── src
+│   ├── chat
+│   │   └── App.tsx
+│   └── home
+│       └── index.ts
+└── package.json
+```
+
+Modern.js will analyze the `src/` directory and get the default entries `chat` and `home`. When the user configures as follows in the `modern.config.ts` file:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      index: './src/home/index.ts',
+    },
+  },
+};
+```
+
+It can be seen that the path of the custom entry `index` is the same as the path of the default entry `home`. During the merge process, `index` will override `home`, and the final entry is as follows:
+
+- `chat -> ./src/chat/App.tsx`
+- `index -> ./src/home/index.ts`

package/docs/configure/app/source/exclude.md

@@ -0,0 +1,10 @@
+# source.exclude
+
+- **Type:** [RuleSetCondition\[\]](https://rspack.rs/config/module#condition)
+- **Default:** `[]`
+
+Specifies JavaScript/TypeScript files that do not need to be compiled. The usage is consistent with [Rule.exclude](https://rspack.rs/config/module#ruleexclude) in Rspack, which supports passing in strings or regular expressions to match the module path.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - source.exclude](https://v2.rsbuild.dev/config/source/exclude).
+:::

package/docs/configure/app/source/global-vars.md

@@ -0,0 +1,106 @@
+# source.globalVars
+
+- **Type:** `Record<string, JSONValue> | Function`
+- **Default:**
+
+```ts
+const defaultGlobalVars = {
+  // The environment variable `process.env.NODE_ENV` will be added by default,
+  // so you don't need to set it in manually.
+  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
+};
+```
+
+Used to define global variables. It can replace expressions like `process.env.FOO` in your code after compile. Such as:
+
+```js
+console.log(process.env.NODE_ENV);
+
+// ⬇️ Turn into being...
+console.log('development');
+```
+
+### Example
+
+In the following example, the `ENABLE_VCONSOLE` and `APP_CONTEXT` are injected into the code:
+
+```js
+export default {
+  source: {
+    globalVars: {
+      ENABLE_VCONSOLE: true,
+      APP_CONTEXT: { answer: 42 },
+    },
+  },
+};
+```
+
+You can use them directly in your code:
+
+```js
+if (ENABLE_VCONSOLE) {
+  // do something
+}
+
+console.log(APP_CONTEXT);
+```
+
+### Function Usage
+
+- **Type:**
+
+```ts
+type GlobalVarsFn = (
+  obj: Record<string, JSONValue>,
+  utils: { env: NodeEnv; target: BuilderTarget },
+) => Record<string, JSONValue> | void;
+```
+
+You can set `source.globalVars` to a function to dynamically setting some environment variables.
+
+For example, dynamically set according to the build target:
+
+```js
+export default {
+  source: {
+    globalVars(obj, { target }) {
+      obj['MY_TARGET'] = target === 'node' ? 'server' : 'client';
+    },
+  },
+};
+```
+
+### Difference with define
+
+You can take `source.globalVars` as the syntax sugar of `source.define`, the only difference is that `source.globalVars` will automatically stringify the value, which makes it easier to set the value of global variables. The values of `globalVars` should be JSON-safe to ensure it can be serialized.
+
+```js
+export default {
+  source: {
+    globalVars: {
+      'process.env.BUILD_VERSION': '0.0.1',
+      'import.meta.foo': { bar: 42 },
+      'import.meta.baz': false,
+    },
+    define: {
+      'process.env.BUILD_VERSION': JSON.stringify('0.0.1'),
+      'import.meta': {
+        foo: JSON.stringify({ bar: 42 }),
+        baz: JSON.stringify(false),
+      },
+    },
+  },
+};
+```
+
+### Precautions
+
+`source.globalVars` injects environment variables through string replacement, so it cannot take effect on dynamic syntaxes such as destructuring.
+
+When using destructuring assignment, Modern.js will not be able to determine whether the variable `NODE_ENV` is associated with the expression `process.env.NODE_ENV` to be replaced, so the following usage is invalid:
+
+```js
+const { NODE_ENV } = process.env;
+console.log(NODE_ENV);
+// ❌ Won't get a string.
+```

package/docs/configure/app/source/include.md

@@ -0,0 +1,36 @@
+# source.include
+
+- **Type:** [RuleSetCondition\[\]](https://rspack.rs/config/module#condition)
+- **Default value:**
+
+```ts
+const defaultInclude = [
+  [{ not: /[\\/]node_modules[\\/]/ }, /\.(?:ts|tsx|jsx|mts|cts)$/],
+];
+```
+
+`source.include` is used to specify additional JavaScript files that need to be compiled. By default, the following files will be compiled:
+
+- TypeScript and JSX files in any directory, with file extensions matching `.ts`, `.tsx`, `.jsx`, `.mts`, `.cts`.
+- JavaScript files not in the `node_modules` directory, with file extensions matching `.js`, `.mjs`, `.cjs`.
+
+:::tip
+Before Rsbuild version 1.4, the default value of `source.include` was:
+
+```ts
+const defaultInclude = [
+  [
+    {
+      and: [APP_ROOT, { not: /[\\/]node_modules[\\/]/ }],
+    },
+    /\.(?:ts|tsx|jsx|mts|cts)$/,
+  ],
+];
+```
+
+The difference from the new version is that `.js`, `.mjs`, `.cjs` files only in the current directory will be compiled.
+:::
+
+:::info
+该配置项的使用方式与 Rsbuild 完全一致。详细信息请参考 [Rsbuild - source.include](https://v2.rsbuild.dev/config/source/include)。
+:::

package/docs/configure/app/source/main-entry-name.md

@@ -0,0 +1,24 @@
+# source.mainEntryName
+
+- **Type:** `string`
+- **Default:** `'index'`
+
+This option is used to configure the main entry name of Modern.js.
+
+By default, the default main entry name of Modern.js is `index`. When using a single entry or the entry name is the same as the `name` field in `package.json`, the corresponding entry will be used as the main entry. This configuration can be used to modify the name of the main entry.
+
+For example, change the main entry name to main:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    mainEntryName: 'main',
+  },
+});
+```
+
+After building, the corresponding HTML output path will be changed to `dist/html/index/index.html`.
+
+:::info
+When the main entry name is modified, other `**ByEntries` configurations also need to be adjusted to use the modified entry name.
+:::

package/docs/configure/app/source/pre-entry.md

@@ -0,0 +1,10 @@
+# source.preEntry
+
+- **Type:** `string | string[]`
+- **Default:** `[]`
+
+Add a script before the entry file of each page. This script will be executed before the page code. It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - source.preEntry](https://v2.rsbuild.dev/config/source/pre-entry).
+:::

package/docs/configure/app/source/react-compiler.md

@@ -0,0 +1,68 @@
+# source.reactCompiler
+
+- **Type:** `boolean | ReactCompilerOptions`
+- **Default:** `undefined` (disabled)
+
+Whether to enable [React Compiler](https://react.dev/learn/react-compiler). React Compiler is a build-time tool that optimizes re-rendering performance of React applications through automatic memoization.
+
+Modern.js implements this capability based on the Rust-based React Compiler built into Rspack's `builtin:swc-loader` (equivalent to setting SWC's `jsc.transform.reactCompiler`), reusing Rspack's built-in SWC transform chain without introducing Babel.
+
+:::tip
+This option is disabled by default. It must be enabled explicitly for any React version, including React 19.
+:::
+
+## Example
+
+### Enable React Compiler (React 19)
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+});
+```
+
+### Using with React 18
+
+The compiled output targets React 19 by default. To use it in React 18 projects, you need to:
+
+1. Install [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) as a **runtime dependency** (the compiled output references it at runtime):
+
+```bash
+npm add react-compiler-runtime
+```
+
+2. Specify the React version via `target`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
+});
+```
+
+### Customize compilation behavior
+
+When passing an object, the options are the same as Rspack's `jsc.transform.reactCompiler`. For example, use `compilationMode: 'annotation'` to only compile functions annotated with the `"use memo"` directive:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+For the complete list of options, see [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) and the [React Compiler configuration docs](https://react.dev/reference/react-compiler/configuration).

package/docs/configure/app/source/transform-import.md

@@ -0,0 +1,27 @@
+# source.transformImport
+
+Transform the import path, which can be used to modularly import the subpath of third-party packages. The functionality is similar to [babel-plugin-import](https://www.npmjs.com/package/babel-plugin-import)。
+
+- **Type:**
+
+```ts
+type TransformImport =
+  | false
+  | Array<{
+      libraryName: string;
+      libraryDirectory?: string;
+      style?: string | boolean;
+      styleLibraryDirectory?: string;
+      camelToDashComponentName?: boolean;
+      transformToDefaultImport?: boolean;
+      customName?: string;
+      customStyleName?: string;
+    }>
+  | Function;
+```
+
+- **Default:** `undefined`
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - source.transformImport](https://v2.rsbuild.dev/config/source/transform-import).
+:::

package/docs/configure/app/split-chunks.md

@@ -0,0 +1,17 @@
+# splitChunks
+
+- **Type:**
+
+```ts
+type SplitChunksConfig =
+  | (Rspack.OptimizationSplitChunksOptions & {
+      preset?: SplitChunksPreset;
+    })
+  | false;
+```
+
+`splitChunks` is used to configure Rsbuild's chunk splitting strategy.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - splitChunks](https://v2.rsbuild.dev/config/split-chunks).
+:::