@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.8.1-ultramodern.1

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).
+:::

package/docs/configure/app/tools/autoprefixer.md

@@ -0,0 +1,44 @@
+# tools.autoprefixer
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+{
+  flexbox: 'no-2009',
+  // Depends on the browserslist config in the project
+  // and the `output.overrideBrowserslist` (higher priority) config
+  overrideBrowserslist: browserslist,
+}
+```
+
+You can modify the config of [autoprefixer](https://github.com/postcss/autoprefixer) by `tools.autoprefixer`.
+
+### Object Type
+
+When `tools.autoprefixer` is configured as `Object` type, it is merged with the default config through Object.assign. For example:
+
+```js
+export default {
+  tools: {
+    autoprefixer: {
+      flexbox: 'no-2009',
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.autoprefixer` is a Function, the default config is passed as the first parameter and can be directly modified or returned as the final result. For example:
+
+```js
+export default {
+  tools: {
+    autoprefixer(config) {
+      // modify flexbox config
+      config.flexbox = 'no-2009';
+    },
+  },
+};
+```

package/docs/configure/app/tools/bundler-chain.md

@@ -0,0 +1,26 @@
+# tools.bundlerChain
+
+- **Type:**
+
+```ts
+type BundlerChainFn = (
+  chain: RspackChain,
+  utils: ModifyBundlerChainUtils,
+) => Promise<void> | void;
+```
+
+- **Default:** `undefined`
+
+You can modify the Rspack configuration by configuring `tools.bundlerChain` which is type of `Function`. The function receives two parameters, the first is the original bundler chain object, and the second is an object containing some utils.
+
+:::tip What is BundlerChain
+
+Bundler chain is a chainable configuration tool implemented based on the Rspack configuration API, which you can use to modify Rspack configuration.
+
+Configurations modified via bundler chain will work on Rspack builds.
+
+:::
+
+> `tools.bundlerChain` is executed earlier than tools.rspack and thus will be overridden by changes in tools.rspack.
+
+For more information, please refer to [Rsbuild#tools.bundlerChain](https://v2.rsbuild.rs/config/tools/bundler-chain).

package/docs/configure/app/tools/css-extract.md

@@ -0,0 +1,33 @@
+# tools.cssExtract
+
+- **Type:**
+
+```ts
+type CSSExtractOptions = {
+  pluginOptions?: Rspack.CssExtractRspackPluginOptions;
+  loaderOptions?: Rspack.CssExtractRspackLoaderOptions;
+};
+```
+
+- **Default:**
+
+```js
+const defaultOptions = {
+  // The loader options
+  loaderOptions: {},
+  // The plugin options
+  pluginOptions: {
+    // The default value of cssPath is `static/css`
+    // while the default value of cssFilename is `[name].[contenthash:8].css`
+    filename: `${cssPath}/${cssFilename}`,
+    chunkFilename: `${cssPath}/async/${cssFilename}`,
+    ignoreOrder: true,
+  },
+};
+```
+
+The config of [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin) can be modified through `tools.cssExtract`.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.cssExtract](https://v2.rsbuild.dev/config/tools/css-extract).
+:::

package/docs/configure/app/tools/css-loader.md

@@ -0,0 +1,17 @@
+# tools.cssLoader
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  modules: rsbuildConfig.output.cssModules,
+  sourceMap: rsbuildConfig.output.sourceMap.css,
+};
+```
+
+The config of [css-loader](https://github.com/webpack-contrib/css-loader) can be modified through `tools.cssLoader`.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.cssLoader](https://v2.rsbuild.dev/config/tools/css-loader).
+:::