@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.100 → 3.5.0-ultramodern.102

package/docs/community/contributing-guide.md

@@ -0,0 +1,252 @@
+# 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
+mise install
+```
+
+### 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,23 @@
+# 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
+
+Modern.js 3.0 no longer ships the `modern upgrade` command. When you need to upgrade a project, follow the manual migration steps in [Upgrade](/guides/get-started/upgrade.md).

package/docs/community/showcase.md

@@ -0,0 +1,24 @@
+# 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
+
+
+[![](/img/features/framework.svg)UltraModern.jsFramework
+
+bleedingdev.github.io](https://bleedingdev.github.io/ultramodern.js/)[![](/img/features/api.svg)EffectFramework
+
+effect.website](https://effect.website/)[![](/img/features/url.svg)TanStack RouterFramework
+
+tanstack.com](https://tanstack.com/router)[![](/img/features/compiler.svg)RspackBuilder
+
+rspack.rs](https://rspack.rs/)[![](/img/features/visual.svg)RspressDoc
+
+rspress.rs](https://rspress.rs/)[![](/img/features/app.svg)Modern.jsDoc
+
+modernjs.dev](https://modernjs.dev/en/)[![](/img/features/frameworks.svg)Module FederationModule
+
+module-federation.io](https://module-federation.io/)

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.mdx → cross-project.md}

@@ -1,15 +1,11 @@
----
-title: crossProject
----
-
 # bff.crossProject
 
 - **Type:** `boolean`
 - **Default:** `false`
 
-import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
-
-<EnableBFFCaution />
+:::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.
 
@@ -21,4 +17,4 @@ export default defineConfig({
 });
 ```
 
-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.html).
+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/{effect.mdx → effect.md}

@@ -1,7 +1,3 @@
----
-title: effect
----
-
 # bff.effect
 
 - **Type:**
@@ -39,9 +35,9 @@ type BffEffectUserConfig = {
 
 - **Default:** `{}`
 
-import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
-
-<EnableBFFCaution />
+:::tip
+Please refer to the [Enable BFF](/guides/advanced-features/bff/function.md#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::
 
 `bff.effect` is only effective when `bff.runtimeFramework` is set to `'effect'`.
 

package/docs/configure/app/bff/{prefix.mdx → prefix.md}

@@ -1,15 +1,11 @@
----
-title: prefix
----
-
 # bff.prefix
 
 - **Type:** `string`
 - **Default:** `/api`
 
-import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
-
-<EnableBFFCaution />
+:::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:
 

package/docs/configure/app/bff/{runtime-framework.mdx → runtime-framework.md}

@@ -1,15 +1,11 @@
----
-title: runtimeFramework
----
-
 # bff.runtimeFramework
 
 - **Type:** `'hono' | 'effect'`
 - **Default:** `'effect'`
 
-import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
-
-<EnableBFFCaution />
+:::tip
+Please refer to the [Enable BFF](/guides/advanced-features/bff/function.md#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::
 
 Controls which runtime framework Modern.js uses for BFF routing.
 

package/docs/configure/app/{builder-plugins.mdx → builder-plugins.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 21
----
-
 # builderPlugins
 
 - **Type:** `RsbuildPlugin[]`
@@ -9,18 +5,18 @@ sidebar_position: 21
 
 Used to configure the Rsbuild plugin.
 
-Rsbuild is the build tool of Modern.js, please read [Build Engine](/guides/concept/builder) 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).
+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) to configure Modern.js framework plugins.
-- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) to configure Rspack plugins.
+- 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) 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.
+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.
 

package/docs/configure/app/dev/{asset-prefix.mdx → asset-prefix.md}

@@ -1,7 +1,3 @@
----
-title: assetPrefix
----
-
 # dev.assetPrefix
 
 - **Type:** `boolean | string | 'auto'`
@@ -9,10 +5,9 @@ title: assetPrefix
 
 This configuration item is used to set the URL prefix of static resources in **development mode**.
 
-import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
-
-<RsbuildConfig configName="dev.assetPrefix" />
-
+:::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) configuration item for setting.
+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.mdx → before-start-url.md}

@@ -1,7 +1,3 @@
----
-title: beforeStartUrl
----
-
 # dev.beforeStartUrl
 
 - **Type:** `() => Promise<void> | void`

package/docs/configure/app/dev/{client.mdx → client.md}

@@ -1,7 +1,3 @@
----
-title: client
----
-
 # dev.client
 
 - **Type:**
@@ -40,6 +36,6 @@ const defaultConfig = {
 
 Configure the client code injected by Modern.js during the development process. This can be used to set the WebSocket URL for HMR.
 
-import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
-
-<RsbuildConfig configName="dev.client" />
+:::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.mdx → host.md}

@@ -1,7 +1,3 @@
----
-title: host
----
-
 # dev.host
 
 - **Type:** `string`

package/docs/configure/app/dev/{https.mdx → https.md}

@@ -1,7 +1,3 @@
----
-title: https
----
-
 # dev.https
 
 - **Type:** `boolean | { key: string; cert: string }`

package/docs/configure/app/dev/{lazy-compilation.mdx → lazy-compilation.md}

@@ -1,7 +1,3 @@
----
-title: lazyCompilation
----
-
 # dev.lazyCompilation
 
 - **Type:**
@@ -37,9 +33,7 @@ type LazyCompilationOptions =
 
 Enable lazy compilation (compilation on demand), implemented based on Rspack's [lazy compilation](https://rspack.rs/guide/features/lazy-compilation) feature.
 
-import RsbuildLink from '@site/src/components/RsbuildLink';
-
 :::info
-The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to <RsbuildLink configName="dev.lazyCompilation"/>。
+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).
+:::

package/docs/configure/app/dev/{mock-dir.mdx → mock-dir.md}

@@ -1,7 +1,3 @@
----
-title: mockDir
----
-
 # dev.mockDir
 
 - **Type:** `string`

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.mdx → server.md}

@@ -1,7 +1,3 @@
----
-title: server
----
-
 # dev.server
 
 - **Type:** `Object`

package/docs/configure/app/dev/{setup-middlewares.mdx → setup-middlewares.md}

@@ -1,7 +1,3 @@
----
-title: setupMiddlewares
----
-
 # dev.setupMiddlewares
 
 - **Type:**
@@ -31,6 +27,6 @@ type SetupMiddlewares = Array<
 
 Provides the ability to execute a custom function and apply custom middlewares.
 
-import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
-
-<RsbuildConfig configName="dev.setupMiddlewares" />
+:::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.mdx → start-url.md}

@@ -1,7 +1,3 @@
----
-title: startUrl
----
-
 # dev.startUrl
 
 - **Type:** `boolean | string | string[] | undefined`
@@ -50,4 +46,3 @@ On MacOS, you can open the specified browser when Dev Server starts, by set envi
 - Brave Browser
 - Vivaldi
 - Chromium
-

package/docs/configure/app/dev/{watch-files.mdx → watch-files.md}

@@ -1,7 +1,3 @@
----
-title: watchFiles
----
-
 # dev.watchFiles
 
 - **Type:**
@@ -26,6 +22,6 @@ type WatchFilesConfig = WatchFiles | WatchFiles[];
 
 Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.
 
-import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
-
-<RsbuildConfig configName="dev.watchFiles" />
+:::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.mdx → write-to-disk.md}

@@ -1,7 +1,3 @@
----
-title: writeToDisk
----
-
 # dev.writeToDisk
 
 - **Type:** `boolean | ((filename: string) => boolean)`
@@ -9,6 +5,6 @@ title: writeToDisk
 
 Controls whether the build output from development mode is written to disk.
 
-import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
-
-<RsbuildConfig configName="dev.writeToDisk" />
+:::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.mdx → source-build.md}

@@ -1,6 +1,4 @@
----
-title: sourceBuild
----
+# sourceBuild
 
 - **Type:** `boolean | PluginSourceBuildOptions`
 - **Default:** `false`