@modern-js/app-tools 3.6.0 → 3.8.0

package/docs/configure/app/dev/mock-dir.md

@@ -0,0 +1,31 @@
+# dev.mockDir
+
+- **Type:** `string`
+- **Default:** `'./config/mock'`
+
+Sets the directory containing the Mock API entry file. Relative paths are
+resolved from the application directory, and absolute paths are also supported.
+Modern.js loads `index.ts` or `index.js` from this directory during development.
+
+For example, move the Mock API entry to `mocks/index.ts`:
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  dev: {
+    mockDir: './mocks',
+  },
+});
+```
+
+This is also useful in a monorepo when multiple applications share one Mock
+directory:
+
+```js title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    mockDir: '../../shared/mocks',
+  },
+});
+```

package/docs/configure/app/dev/progress-bar.md

@@ -0,0 +1,19 @@
+# dev.progressBar
+
+- **Type:**
+
+```ts
+type ProgressBar =
+  | boolean
+  | {
+      id?: string;
+    };
+```
+
+- **Default:** true
+
+Whether to display progress bar during compilation.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.progressBar](https://v2.rsbuild.dev/config/dev/progress-bar).
+:::

package/docs/configure/app/dev/server.md

@@ -0,0 +1,124 @@
+# dev.server
+
+- **Type:** `Object`
+- **Default:** `{}`
+
+The config of DevServer can be modified through `dev.server`.
+
+### compress
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to enable gzip compression for served static assets.
+
+If you want to disable the gzip compression, you can set `compress` to `false`:
+
+```ts
+export default {
+  dev: {
+    server: {
+      compress: false,
+    },
+  },
+};
+```
+
+For more details, please refer to the [Rsbuild - server.compress](https://v2.rsbuild.rs/config/server/compress) documentation.
+
+### headers
+
+- **Type:** `Record<string, string>`
+- **Default:** `undefined`
+
+Adds headers to all responses.
+
+```js
+export default {
+  dev: {
+    server: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+For more details, please refer to the [Rsbuild - server.headers](https://v2.rsbuild.rs/config/server/headers) documentation.
+
+### historyApiFallback
+
+- **Type:** `boolean | ConnectHistoryApiFallbackOptions`
+- **Default:** `false`
+
+The index.html page will likely have to be served in place of any 404 responses. Enable `dev.server.historyApiFallback` by setting it to `true`:
+
+```js
+export default {
+  dev: {
+    server: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+For more configuration options, please refer to the [Rsbuild - server.historyApiFallback](https://v2.rsbuild.rs/config/server/history-api-fallback) documentation.
+
+### watch
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to watch files change in directories such as `mock/`, `server/`, `api/`.
+
+For more details, please refer to the [Rsbuild - dev.watchFiles](https://v2.rsbuild.rs/config/dev/watch-files) documentation.
+
+### cors
+
+- **Type:** `boolean | import('cors').CorsOptions`
+
+Configure CORS (Cross-Origin Resource Sharing) for the development server.
+
+The default configuration for `cors` in Modern.js follows Rsbuild's defaults:
+
+```ts
+const defaultAllowedOrigins =
+  /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/;
+
+const defaultOptions = {
+  // Default allowed:
+  // - localhost
+  // - 127.0.0.1
+  // - [::1]
+  origin: defaultAllowedOrigins,
+};
+```
+
+For more configuration options and detailed usage, please refer to the [Rsbuild - server.cors](https://v2.rsbuild.rs/config/server/cors) documentation.
+
+### proxy
+
+- **Type:** `ProxyOptions[] | Record<string, string | ProxyOptions>`
+- **Default:** `undefined`
+
+Configure proxy rules for the dev server, and forward requests to the specified service.
+
+```js
+export default {
+  dev: {
+    server: {
+      proxy: {
+        // http://localhost:8080/api -> https://example.com/api
+        // http://localhost:8080/api/foo -> https://example.com/api/foo
+        '/api': 'https://example.com',
+      },
+    },
+  },
+};
+```
+
+:::tip
+This option is the same as Rsbuild's `server.proxy` option, see [Rsbuild - server.proxy](https://v2.rsbuild.rs/config/server/proxy) for detailed usage.
+:::

package/docs/configure/app/dev/setup-middlewares.md

@@ -0,0 +1,32 @@
+# dev.setupMiddlewares
+
+- **Type:**
+
+```ts
+type RequestHandler = (req: any, res: any, next: () => void) => void;
+
+type ExposeServerApis = {
+  sockWrite: (
+    type: string,
+    data?: string | boolean | Record<string, any>,
+  ) => void;
+};
+
+type SetupMiddlewares = Array<
+  (
+    middlewares: {
+      unshift: (...handlers: RequestHandler[]) => void;
+      push: (...handlers: RequestHandler[]) => void;
+    },
+    server: ExposeServerApis,
+  ) => void
+>;
+```
+
+- **Default:** `undefined`
+
+Provides the ability to execute a custom function and apply custom middlewares.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.setupMiddlewares](https://v2.rsbuild.dev/config/dev/setup-middlewares).
+:::

package/docs/configure/app/dev/start-url.md

@@ -0,0 +1,48 @@
+# dev.startUrl
+
+- **Type:** `boolean | string | string[] | undefined`
+- **Default:** `undefined`
+
+`dev.startUrl` is used to set the URL of the page that automatically opens in the browser when Dev Server starts.
+
+By default, no page will be opened.
+
+You can set it to the following values:
+
+```js
+export default {
+  dev: {
+    // Open the project's default preview page, equivalent to `http://localhost:<port>`
+    startUrl: true,
+    // Open the specified page
+    startUrl: 'http://localhost:8080',
+    // Open multiple pages
+    startUrl: ['http://localhost:8080', 'http://localhost:8080/about'],
+  },
+};
+```
+
+### Port placeholder
+
+Since the port number may change, you can use the `<port>` placeholder to refer to the current port number, and Modern.js will automatically replace the placeholder with the actual listening port number.
+
+```js
+export default {
+  dev: {
+    startUrl: 'http://localhost:<port>/home',
+  },
+};
+```
+
+### Open the specified browser
+
+On MacOS, you can open the specified browser when Dev Server starts, by set environment variable `BROWSER`, support values:
+
+- Google Chrome Canary
+- Google Chrome Dev
+- Google Chrome Beta
+- Google Chrome
+- Microsoft Edge
+- Brave Browser
+- Vivaldi
+- Chromium

package/docs/configure/app/dev/watch-files.md

@@ -0,0 +1,27 @@
+# dev.watchFiles
+
+- **Type:**
+
+```ts
+type WatchFiles =
+  | {
+      paths: string | string[];
+      type?: 'reload-page';
+      // watch options for chokidar
+      options?: WatchOptions;
+    }
+  | {
+      paths: string | string[];
+      type?: 'reload-server';
+    };
+
+type WatchFilesConfig = WatchFiles | WatchFiles[];
+```
+
+- **Default:** `undefined`
+
+Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.watchFiles](https://v2.rsbuild.dev/config/dev/watch-files).
+:::

package/docs/configure/app/dev/write-to-disk.md

@@ -0,0 +1,10 @@
+# dev.writeToDisk
+
+- **Type:** `boolean | ((filename: string) => boolean)`
+- **Default:** `(file) => !file.includes('.hot-update.')`
+
+Controls whether the build output from development mode is written to disk.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.writeToDisk](https://v2.rsbuild.dev/config/dev/write-to-disk).
+:::

package/docs/configure/app/experiments/source-build.md

@@ -0,0 +1,31 @@
+# sourceBuild
+
+- **Type:** `boolean | PluginSourceBuildOptions`
+- **Default:** `false`
+
+Used to enable the ability for source code building. When this configuration option is enabled, Modern.js will read the source code files corresponding to the `source` field in the sub-project's package.json and compile them.
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+More detail can see ["Source Code Build Mode"](https://modernjs.dev/en/guides/advanced-features/source-build.html)。
+
+### Options
+
+`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options). You can pass plugin options like this:
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: {
+      sourceField: 'my-source',
+      resolvePriority: 'output',
+    },
+  },
+};
+```

package/docs/configure/app/html/app-icon.md

@@ -0,0 +1,28 @@
+# html.appIcon
+
+- **Type:**
+
+```ts
+type AppIconItem = {
+  src: string;
+  size: number;
+  target?: 'apple-touch-icon' | 'web-app-manifest';
+};
+
+type AppIcon = {
+  name?: string;
+  icons: AppIconItem[];
+  filename?: string;
+};
+```
+
+- **Default:** `undefined`
+
+Set the web application icons to display when added to the home screen of a mobile device:
+
+- Generate the web app manifest file and its `icons` field.
+- Generate the `apple-touch-icon` and `manifest` tags in the HTML file.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.appIcon](https://v2.rsbuild.dev/config/html/app-icon).
+:::

package/docs/configure/app/html/crossorigin.md

@@ -0,0 +1,10 @@
+# html.crossorigin
+
+- **Type:** `boolean | 'anonymous' | 'use-credentials'`
+- **Default:** `false`
+
+Set the [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) attribute of the `<script>` and `<style>` tags.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.crossorigin](https://v2.rsbuild.dev/config/html/crossorigin).
+:::

package/docs/configure/app/html/favicon.md

@@ -0,0 +1,16 @@
+# html.favicon
+
+- **Type:** `string ｜ Function`
+- **Default:** `undefined`
+
+Set the favicon icon path for all pages, can be set as:
+
+- a URL.
+- an absolute path to the file.
+- a relative path relative to the project root directory.
+
+After config this option, the favicon will be automatically copied to the dist directory during the compilation, and the corresponding `link` tag will be added to the HTML.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.favicon](https://v2.rsbuild.dev/config/html/favicon).
+:::

package/docs/configure/app/html/inject.md

@@ -0,0 +1,10 @@
+# html.inject
+
+- **Type:** `'head' | 'body' | boolean | Function`
+- **Default:** `'head'`
+
+Set the inject position of the `<script>` tag.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.inject](https://v2.rsbuild.dev/config/html/inject).
+:::

package/docs/configure/app/html/meta.md

@@ -0,0 +1,24 @@
+# html.meta
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultMeta = {
+  charset: { charset: 'utf-8' },
+  viewport:
+    'width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no',
+  'http-equiv': { 'http-equiv': 'x-ua-compatible', content: 'ie=edge' },
+  renderer: 'webkit',
+  layoutmode: 'standard',
+  imagemode: 'force',
+  'wap-font-scale': 'no',
+  'format-detection': 'telephone=no',
+};
+```
+
+Configure the `<meta>` tag of the HTML.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.meta](https://v2.rsbuild.dev/config/html/meta).
+:::

package/docs/configure/app/html/mount-id.md

@@ -0,0 +1,10 @@
+# html.mountId
+
+- **Type:** `string`
+- **Default:** `'root'`
+
+By default, the `root` element is included in the HTML template for component mounting, and the element id can be modified through `mountId`.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.mountId](https://v2.rsbuild.dev/config/html/mount-id).
+:::

package/docs/configure/app/html/output-structure.md

@@ -0,0 +1,10 @@
+# html.outputStructure
+
+- **Type:** `'flat' | 'nested'`
+- **Default:** `'nested'`
+
+Define the directory structure of the HTML output files.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.outputStructure](https://v2.rsbuild.dev/config/html/output-structure).
+:::

package/docs/configure/app/html/script-loading.md

@@ -0,0 +1,10 @@
+# html.scriptLoading
+
+- **Type:** `'defer' | 'blocking' | 'module'`
+- **Default:** `'defer'`
+
+Used to set how `<script>` tags are loaded.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.scriptLoading](https://v2.rsbuild.dev/config/html/script-loading).
+:::

package/docs/configure/app/html/tags.md

@@ -0,0 +1,15 @@
+# html.tags
+
+- **Type:**
+
+```ts
+type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
+```
+
+- **Default:** `undefined`
+
+Modifies the tags that are injected into the HTML page.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.tags](https://v2.rsbuild.dev/config/html/tags).
+:::

package/docs/configure/app/html/template-parameters.md

@@ -0,0 +1,33 @@
+# html.templateParameters
+
+- **Type:** `Record<string, unknown> | Function`
+- **Default:**
+
+```ts
+type DefaultParameters = {
+  mountId: string; // the value of `html.mountId` config
+  entryName: string; // entry name
+  assetPrefix: string; // the value of dev.assetPrefix or output.assetPrefix configs
+  compilation: Compilation; // Compilation object of Rspack
+  rspackConfig: Rspack.Configuration; // Rspack config object
+  // generated by html-rspack-plugin
+  htmlPlugin: {
+    tags: {
+      headTags: HtmlTagObject[];
+      bodyTags: HtmlTagObject[];
+    };
+    files: {
+      publicPath: string;
+      js: Array<string>;
+      css: Array<string>;
+      favicon?: string;
+    };
+  };
+};
+```
+
+Define the parameters in the HTML template, corresponding to the `templateParameters` config of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin). You can use the config as an object or a function.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.templateParameters](https://v2.rsbuild.dev/config/html/template-parameters).
+:::

package/docs/configure/app/html/template.md

@@ -0,0 +1,10 @@
+# html.template
+
+- **Type:** `string | Function`
+- **Default:**
+
+Specifies the file path for the HTML template, which can be a relative or absolute path.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.template](https://v2.rsbuild.dev/config/html/template).
+:::

package/docs/configure/app/html/title.md

@@ -0,0 +1,18 @@
+# html.title
+
+- **Type:** `string ｜ Function`
+- **Default:** `''`
+
+Set the title tag of the HTML page, for example:
+
+```js
+export default {
+  html: {
+    title: 'example',
+  },
+};
+```
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.title](https://v2.rsbuild.dev/config/html/title).
+:::

package/docs/configure/app/output/asset-prefix.md

@@ -0,0 +1,11 @@
+# output.assetPrefix
+
+- **Type:** `string | 'auto'`
+- **Default:** `'/'`
+
+In production mode, use this option to set the URL prefix for static assets, such as setting it to a CDN URL.
+
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.assetPrefix](https://v2.rsbuild.dev/config/output/asset-prefix).
+:::

package/docs/configure/app/output/assets-retry.md

@@ -0,0 +1,77 @@
+# output.assetsRetry
+
+- **Type:** `Object`
+
+`output.assetsRetry` is used to configure the retry of assets.The type of `AssetsRetryOptions` is as follows:
+
+```ts
+export type AssetsRetryHookContext = {
+  times: number;
+  domain: string;
+  url: string;
+  tagName: string;
+};
+
+export type AssetsRetryOptions = {
+  type?: string[];
+  domain?: string[];
+  max?: number;
+  test?: string | ((url: string) => boolean);
+  crossOrigin?: boolean | 'anonymous' | 'use-credentials';
+  inlineScript?: boolean;
+  onRetry?: (options: AssetsRetryHookContext) => void;
+  onSuccess?: (options: AssetsRetryHookContext) => void;
+  onFail?: (options: AssetsRetryHookContext) => void;
+};
+```
+
+- **Default:** `undefined`
+
+- Since this feature injects some runtime code into your HTML and [Rspack Runtime](https://rspack.rs/api/runtime-api/module-variables), it is disabled by default. To enable it, provide an object for the option, for example:
+
+```js
+export default {
+  output: {
+    assetsRetry: {},
+  },
+};
+```
+
+When you enable this feature, the default configuration for `assetsRetry` is:
+
+```ts
+export const defaultAssetsRetryOptions: AssetsRetryOptions = {
+  type: ['script', 'link', 'img'],
+  domain: [],
+  max: 3,
+  test: '',
+  crossOrigin: false,
+  inlineScript: false,
+  onRetry: () => {},
+  onSuccess: () => {},
+  onFail: () => {},
+};
+```
+
+### Example
+
+You can also customize your retry logic using the `assetsRetry` options.
+
+For example, setting `assetsRetry.domain` to specify the retry domain when assets fail to load.
+
+As an example, you can specify a list of fallback domains via `assetsRetry.domain`. The first domain in the list should match the domain used in your [`assetsPrefix`](/configure/app/output/asset-prefix.md) configuration:
+
+```js
+export default {
+  output: {
+    assetsRetry: {
+      domain: ['cdn1.com', 'cdn2.com', 'cdn3.com'],
+    },
+    assetsPrefix: 'https://cdn1.com', // or '//cdn1.com'
+  },
+};
+```
+
+With the configuration above, if an asset fails to load from `cdn1.com`, requests will automatically fall back to `cdn2.com`. If `cdn2.com` also fails, the request will continue to `cdn3.com`.
+
+`assetsRetry` is implemented based on the Assets Retry plugin of Rsbuild and provides the same configuration options. You can refer to [Rsbuild - Assets Retry Plugin](https://github.com/rstackjs/rsbuild-plugin-assets-retry) to understand all available configuration options.

package/docs/configure/app/output/charset.md

@@ -0,0 +1,10 @@
+# output.charset
+
+- **Type:** `'ascii' | 'utf8'`
+- **Default:** `'ascii'`
+
+The `charset` config allows you to specify the [character encoding](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding) for output files to ensure they are displayed correctly in different environments.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.charset](https://v2.rsbuild.dev/config/output/charset).
+:::

package/docs/configure/app/output/clean-dist-path.md

@@ -0,0 +1,16 @@
+# output.cleanDistPath
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to clean all files in the dist path before starting compilation.
+
+By default, Modern.js will automatically clean up the files in the dist directory, you can disable this behavior by setting `cleanDistPath` to `false`.
+
+```js
+export default {
+  output: {
+    cleanDistPath: false,
+  },
+};
+```