@modern-js/app-tools 3.7.0 → 3.8.1

package/docs/community/contributing-guide.md

@@ -0,0 +1,253 @@
+# Contributing Guide
+
+Thanks for that you are interested in contributing to Modern.js. Before starting your contribution, please take a moment to read the following guidelines.
+
+## Setup the Dev Environment
+
+### Fork the Repo
+
+[Fork](https://help.github.com/articles/fork-a-repo/) this repository to your
+own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local.
+
+### Install Node.js
+
+We recommend using Node.js 22. You can check your currently used Node.js version with the following command:
+
+```bash
+node -v
+```
+
+If you do not have Node.js installed in your current environment, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install it.
+
+Here is an example of how to install the Node.js 22 LTS version via nvm:
+
+```bash
+# Install the LTS version of Node.js 22
+nvm install 22 --lts
+
+# Make the newly installed Node.js 22 as the default version
+nvm alias default 22
+
+# Switch to the newly installed Node.js 22
+nvm use 22
+```
+
+### Install pnpm
+
+```sh
+# Enable pnpm with corepack, only available on Node.js >= `v14.19.0`
+corepack enable
+```
+
+### Install Dependencies
+
+```sh
+pnpm install
+```
+
+What this will do:
+
+- Install all dependencies
+- Create symlinks between packages in the monorepo
+- Run the `prepare` script to build all packages (this will take some time, but is necessary to make ensure all packages are built)
+
+> A full rebuild of all packages is generally not required after this. If a new feature you are developing requires an updated version of another package, it is usually sufficient to build the changed dependencies.
+
+### Set Git Email
+
+Please make sure you have your email set up in `<https://github.com/settings/emails>`. This will be needed later when you want to submit a pull request.
+
+Check that your git client is already configured the email:
+
+```sh
+git config --list | grep email
+```
+
+Set the email to global config:
+
+```sh
+git config --global user.email "SOME_EMAIL@example.com"
+```
+
+Set the email for local repo:
+
+```sh
+git config user.email "SOME_EMAIL@example.com"
+```
+
+## Making Changes and Building
+
+Once you have set up the local development environment in your forked repo, we can start development.
+
+### Checkout A New Branch
+
+It is recommended to develop on a new branch, as it will make things easier later when you submit a pull request:
+
+```sh
+git checkout -b MY_BRANCH_NAME
+```
+
+### Build the Package
+
+To build the package you want to change, first open the package directory, then run the `build` command:
+
+```sh
+# Replace some-path with the path of the package you want to work on
+cd ./packages/some-path
+pnpm run build
+```
+
+Alternatively, you can build the package from the root directory of the repository using the `--filter` option:
+
+```sh
+pnpm run --filter @modern-js/some-package build
+```
+
+Build all packages:
+
+```sh
+pnpm run prepare
+```
+
+If you need to clean all `node_modules/*` in the project, run the `reset` command:
+
+```sh
+pnpm run reset
+```
+
+## Testing
+
+### Add New Tests
+
+If you've fixed a bug or added code that should be tested, then add some tests.
+
+Modern.js uses [Rstest](https://rstest.rs/) for unit tests across the repository. You can add test cases in the `<PACKAGE_DIR>/tests` folder, using Rstest syntax.
+
+### Run Unit Tests
+
+Before submitting a pull request, it's important to make sure that the changes haven't introduced any regressions or bugs. You can run the unit tests for the project by executing the following command:
+
+```sh
+pnpm run test
+```
+
+Alternatively, you can run the unit tests of single package using the `--filter` option:
+
+```sh
+pnpm run --filter @modern-js/some-package test
+```
+
+### Run E2E Tests
+
+In addition to the unit tests, the Modern.js also includes end-to-end (E2E) tests, which checks the functionality of the application as a whole.
+
+You can run the `test:e2e` command to run the E2E tests:
+
+```sh
+pnpm run test:e2e
+```
+
+If you need to run a specified test, you can add keywords to filter:
+
+```sh
+# Only run test cases with the copy-assets keyword
+npx rstest copy-assets
+```
+
+## Linting
+
+To help maintain consistency and readability of the codebase, we use a ESLint to lint the codes.
+
+You can run the Linter by executing the following command:
+
+```sh
+pnpm run lint
+```
+
+## Benchmarking
+
+You can input `!bench-framework` or `!bench-module` in the comment area of ​​the PR to do benchmarking on `@modern-js/app-tools` and `@modern-js/module-tools` respectively (you need to have Collaborator and above permissions).
+
+You can focus on metrics related to build time and bundle size based on the comparison table output by comments to assist you in making relevant performance judgments and decisions.
+
+Dependencies installation-related metrics base on publishing process, so the data is relatively lagging and is for reference only.
+
+## Documentation
+
+Currently Modern.js provides documentation in English and Chinese. If you can use Chinese, please update both documents at the same time. Otherwise, just update the English documentation.
+
+You can find all the documentation in the `packages/document` folder:
+
+```bash
+root
+└─ packages
+   └─ document  # Documentation for Modern.js Framework
+```
+
+This website is built with Rspress, the document content can be written using markdown or mdx syntax. You can refer to the [Rspress Website](https://rspress.rs/) for detailed usage.
+
+The source code of Rspress can be found in [this repo](https://github.com/web-infra-dev/rspress).
+
+## Submitting Changes
+
+### Add a Changeset
+
+Modern.js is using [Changesets](https://github.com/changesets/changesets) to manage the versioning and changelogs.
+
+If you've changed some packages, you need add a new changeset for the changes. Please run `change` command to select the changed packages and add the changeset info.
+
+```sh
+pnpm run change
+```
+
+### Committing your Changes
+
+Commit your changes to your forked repo, and [create a pull request](https://help.github.com/articles/creating-a-pull-request/).
+
+### Format of PR titles
+
+The format of PR titles follow Conventional Commits.
+
+An example:
+
+```
+feat(plugin-swc): Add `xxx` config
+^    ^    ^
+|    |    |__ Subject
+|    |_______ Scope
+|____________ Type
+```
+
+## Publishing
+
+We use **Modern.js Monorepo Solution** to manage version and changelog.
+
+Repository maintainers can publish a new version of all packages to npm.
+
+Here are the steps to publish (we generally use CI for releases and avoid publishing npm packages locally):
+
+1. Pull latest code from the `main` branch.
+2. Install:
+
+```sh
+pnpm i
+```
+
+3. Build packages:
+
+```sh
+pnpm run prepare
+```
+
+4. Bump version:
+
+```sh
+pnpm run bump
+```
+
+5. Commit the version change.
+
+```sh
+git add .
+git commit -m "Release va.b.c"
+```

package/docs/community/releases.md

@@ -0,0 +1,27 @@
+# Releases
+
+## Changelog
+
+Please visit [GitHub - Releases](https://github.com/web-infra-dev/modern.js/releases) to see what has changed with each release of Modern.js.
+
+## Version Specification
+
+Modern.js follows the [Semantic Versioning](https://semver.org) specification.
+
+- Major version: Contains incompatible API changes.
+- Minor version: Contains backward compatible functional changes.
+- Patch version: Contains backwards compatible bug fixes
+
+## Release Cycle
+
+- Modern.js generally releases an official release every Thursday.
+- If critical bugs appear, we will release a revised version on the same day.
+- We expect to keep Modern.js v2 stable and compatible, there are currently no plans to release the next major version.
+
+## Version Upgrade
+
+When you need to upgrade the Modern.js version in your project, you can use the `modern upgrade` command, refer to [Upgrade](/guides/get-started/upgrade.md).
+
+```bash
+npx modern upgrade
+```

package/docs/community/showcase.md

@@ -0,0 +1,34 @@
+# Showcase
+
+Welcome to the Modern.js showcase page! Here, we present a collection of websites that have been built using Modern.js.
+
+If you have built a website using Modern.js, we would love for you to share it with the community. Simply reply to the GitHub discussion thread with a link to your website. We will collect content on a regular basis and display it on the current page.
+
+## The Cases
+
+
+[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/tiktok-seller-showcase-08172.png)Tiktok SellerFramework
+
+seller-us-accounts.tiktok.com](https://seller-us-accounts.tiktok.com/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/tiktok-steamer-showcase-08172.png)Tiktok StreamerFramework
+
+shop.tiktok.com](https://shop.tiktok.com/streamer/welcome)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/tiktok-shop-partner-0817.png)Tiktok Shop PartnerFramework
+
+partner-us.tiktok.com](https://partner-us.tiktok.com/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/doubao-showcase-0817.png)DoubaoFramework
+
+www.doubao.com](https://www.doubao.com/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/volctrans-0424.jpeg)VolctransFramework
+
+translate.volcengine.com](https://translate.volcengine.com/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/writingo-0424.jpeg)WritingoFramework
+
+writingo.net](https://writingo.net/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/rspack-0424.jpeg)RspackDoc
+
+rspack.rs](https://rspack.rs/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/modernjs-dev-0425.jpeg)Modern.jsDoc
+
+modernjs.dev](https://modernjs.dev/en/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/shidianbaike-0424.jpeg)Shidian BaikeFramework
+
+shidian.baike.com](https://shidian.baike.com/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/xiaohe-0424.png)XiaoheFramework
+
+xiaohe.cn](https://xiaohe.cn/)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/dongchedi-0425.png)DongchediBuilder
+
+m.dcdapp.com](https://m.dcdapp.com/motor/feoffline/usedcar_channel/channel.html)[![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/showcase/developer-volcengine-0425.png)Volcengine DeveloperFramework
+
+developer.volcengine.com](https://developer.volcengine.com/)

package/docs/community/team.md

@@ -0,0 +1,14 @@
+# Meet the Team
+
+The development of Modern.js is driven by ByteDance's Modern.js team and community contributors.
+
+## Core Team Members
+
+The Modern.js core team members:
+
+
+## All Contributors
+
+Thanks to the following friends for their contributions to Modern.js:
+
+[![contributors](https://opencollective.com/modernjs/contributors.svg?width=890&button=false)](https://github.com/web-infra-dev/modern.js/graphs/contributors)

package/docs/configure/app/bff/cross-project.md

@@ -0,0 +1,20 @@
+# bff.crossProject
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+:::tip
+Please refer to the [Enable BFF](/guides/advanced-features/bff/function.md#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::
+
+This configuration is used to enable BFF cross-project invocation functionality. When enabled, the current project can be used as a BFF producer, generating an SDK that can be directly called by other projects.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+For detailed configuration and usage of BFF cross-project invocation, please refer to the [BFF Cross-Project Invocation Guide](/guides/advanced-features/bff/cross-project.md).

package/docs/configure/app/bff/prefix.md

@@ -0,0 +1,29 @@
+# bff.prefix
+
+- **Type:** `string`
+- **Default:** `/api`
+
+:::tip
+Please refer to the [Enable BFF](/guides/advanced-features/bff/function.md#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::
+
+By default, the prefix for accessing routes in the BFF API directory is `/api`, as shown in the following directory structure:
+
+```bash
+api
+└── hello.ts
+```
+
+The route corresponding to `api/hello.ts` when accessed is `localhost:8080/api/hello`.
+
+This configuration option can modify the default route prefix:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    prefix: '/api-demo',
+  },
+});
+```
+
+The corresponding route for `api/hello.ts` when accessed is `localhost:8080/api-demo/hello`.

package/docs/configure/app/builder-plugins.md

@@ -0,0 +1,66 @@
+# builderPlugins
+
+- **Type:** `RsbuildPlugin[]`
+- **Default:** `[]`
+
+Used to configure the Rsbuild plugin.
+
+Rsbuild is the build tool of Modern.js, please read [Build Engine](/guides/concept/builder.md) for background. If you want to know how to write Rsbuild plugins, you can refer to [Rsbuild - Plugin System](https://v2.rsbuild.rs/plugins/dev/index).
+
+## Precautions
+
+This option **is used to configure the Rsbuild plugins**. If you need to configure other types of plugins, please select the corresponding configs:
+
+- Use [plugins](/configure/app/plugins.md) to configure Modern.js framework plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain.md) to configure Rspack plugins.
+
+## When to use
+
+In most scenarios, we recommend you to use the Modern.js framework plugin, which can be registered through the [plugins](/configure/app/plugins.md) config. Because the API provided by the framework plugin is richer and more capable, while the API provided by the Rsbuild plugin can only be used to build scenes.
+
+When you need to reference some existing Rsbuild plugins (and there is no related capability in Modern.js), or reuse Rsbuild plugins between different frameworks, you can use the `builderPlugins` field to register them.
+
+## Example
+
+Below is an example of using the Rsbuild plugin.
+
+### Using plugins on npm
+
+To use a plugin on npm, you need to install the plugin through the package manager and import it.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from 'my-rsbuild-plugin';
+
+export default defineConfig({
+  builderPlugins: [myRsbuildPlugin()],
+});
+```
+
+### Using local plugins
+
+Use the plugin in the local code repository, you can import it directly through the relative path import.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from './plugin/myRsbuildPlugin';
+
+export default defineConfig({
+  builderPlugins: [myRsbuildPlugin()],
+});
+```
+
+### Plugin configuration options
+
+If the plugin provides some custom configuration options, you can pass in the configuration through the parameters of the plugin function.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from 'my-rsbuild-plugin';
+
+export default defineConfig({
+  builderPlugins: [
+    myRsbuildPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

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

@@ -0,0 +1,13 @@
+# dev.assetPrefix
+
+- **Type:** `boolean | string | 'auto'`
+- **Default:** `'/'`
+
+This configuration item is used to set the URL prefix of static resources in **development mode**.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.assetPrefix](https://v2.rsbuild.dev/config/dev/asset-prefix).
+:::
+:::warning
+Please note that this configuration item is only applicable in development mode. In production mode, please use the [output.assetPrefix](/configure/app/output/asset-prefix.md) configuration item for setting.
+:::

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

@@ -0,0 +1,17 @@
+# dev.beforeStartUrl
+
+- **Type:** `() => Promise<void> | void`
+- **Default:** `undefined`
+
+`dev.beforeStartUrl` is used to execute a callback function before opening the `startUrl`, this config needs to be used together with `dev.startUrl`.
+
+```js
+export default {
+  dev: {
+    startUrl: true,
+    beforeStartUrl: async () => {
+      await doSomeThing();
+    },
+  },
+};
+```

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

@@ -0,0 +1,41 @@
+# dev.client
+
+- **Type:**
+
+```ts
+type Client = {
+  // The protocol name for the WebSocket request
+  protocol?: 'ws' | 'wss';
+  // The path for the WebSocket request
+  path?: string;
+  // The port number for the WebSocket request
+  port?: string | number;
+  // The host for the WebSocket request
+  host?: string;
+  // The maximum number of reconnection attempts after a WebSocket request is disconnected.
+  reconnect?: number;
+  // Whether to display an error overlay in the browser when a compilation error occurs
+  overlay?: boolean;
+};
+```
+
+- **Default:**
+
+```js
+const defaultConfig = {
+  path: '/webpack-hmr',
+  port: '<port>',
+  // By default it is set to "location.hostname"
+  host: '',
+  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
+  protocol: undefined,
+  reconnect: 100,
+  overlay: false,
+};
+```
+
+Configure the client code injected by Modern.js during the development process. This can be used to set the WebSocket URL for HMR.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.client](https://v2.rsbuild.dev/config/dev/client).
+:::

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

@@ -0,0 +1,10 @@
+# dev.hmr
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to enable Hot Module Replacement.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.hmr](https://v2.rsbuild.dev/config/dev/hmr).
+:::

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

@@ -0,0 +1,18 @@
+# dev.host
+
+- **Type:** `string`
+- **Default:** `0.0.0.0`
+
+Specify the host that the dev server listens to.
+
+By default, the dev server will listen to `0.0.0.0`, which means listening to all network interfaces, including `localhost` and public network addresses.
+
+If you want the dev server to listen only on `localhost`, you can set it to:
+
+```ts
+export default {
+  dev: {
+    host: 'localhost',
+  },
+};
+```

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

@@ -0,0 +1,77 @@
+# dev.https
+
+- **Type:** `boolean | { key: string; cert: string }`
+- **Default:** `false`
+
+After configuring this option, you can enable HTTPS Dev Server, and disabling the HTTP Dev Server.
+
+HTTP:
+
+```bash
+  > Local: http://localhost:8080/
+  > Network: http://192.168.0.1:8080/
+```
+
+HTTPS:
+
+```bash
+  > Local: https://localhost:8080/
+  > Network: https://192.168.0.1:8080/
+```
+
+#### Automatically generate certificates
+
+You can directly set `https` to `true`, Modern.js will automatically generate the HTTPS certificate based on [devcert](https://github.com/davewasmer/devcert).
+
+When using this method, you need to manually install the [devcert](https://github.com/davewasmer/devcert) dependency in your project:
+
+```bash
+# npm
+npm install devcert@1.2.2 -D
+
+# yarn
+yarn add devcert@1.2.2 -D
+
+# pnpm
+pnpm add devcert@1.2.2 -D
+```
+
+Then configure `dev.https` to `true`:
+
+```ts
+export default {
+  dev: {
+    https: true,
+  },
+};
+```
+
+The devcert has some limitations, it does not currently support IP addresses yet.
+
+:::tip
+The https proxy automatically installs the certificate and needs root authority, please enter the password according to the prompt.
+**The password is only used to trust the certificate, and will not be leaked or be used elsewhere**.
+:::
+
+#### Manually set the certificate
+
+You can also manually pass in the certificate and the private key required in the `dev.https` option. This parameter will be directly passed to the createServer method of the https module in Node.js.
+
+For details, please refer to [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener).
+
+```ts
+import fs from 'fs';
+
+export default {
+  dev: {
+    https: {
+      key: fs.readFileSync('certificates/private.pem'),
+      cert: fs.readFileSync('certificates/public.pem'),
+    },
+  },
+};
+```
+
+#### Clean up cert cache
+
+The certificate created by devcert is saved in `~/Library/Application\ Support/devcert`. You may do some cleanup if needed.

package/docs/configure/app/dev/lazy-compilation.md

@@ -0,0 +1,39 @@
+# dev.lazyCompilation
+
+- **Type:**
+
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      /**
+       * Enable lazy compilation for entries.
+       */
+      entries?: boolean;
+      /**
+       * Enable lazy compilation for dynamic imports.
+       */
+      imports?: boolean;
+      /**
+       * Specify which imported modules should be lazily compiled.
+       */
+      test?: RegExp | ((m: Module) => boolean);
+      /**
+       * The path to a custom runtime code that overrides the default lazy compilation client.
+       */
+      client?: string;
+      /**
+       * Tells the client the server URL that needs to be requested.
+       */
+      serverUrl?: string;
+    };
+```
+
+- **Default:** `false`
+
+Enable lazy compilation (compilation on demand), implemented based on Rspack's [lazy compilation](https://rspack.rs/guide/features/lazy-compilation) feature.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.lazyCompilation](https://v2.rsbuild.dev/config/dev/lazy-compilation)。
+In Rspack build mode,
+:::

package/docs/configure/app/dev/live-reload.md

@@ -0,0 +1,10 @@
+# dev.liveReload
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to reload the page when source files are changed.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - dev.liveReload](https://v2.rsbuild.dev/config/dev/live-reload).
+:::