@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/en/community/contributing-guide.mdx

@@ -0,0 +1,257 @@
+---
+sidebar_position: 3
+---
+
+# 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.
+
+You can add unit test cases in the `<PACKAGE_DIR>/tests` folder. The test syntax is based on [Rstest](https://rstest.rs/).
+
+### 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/en/community/releases.mdx

@@ -0,0 +1,31 @@
+---
+sidebar_position: 2
+---
+
+# 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).
+
+```bash
+npx modern upgrade
+```

package/docs/en/community/showcase.mdx

@@ -0,0 +1,15 @@
+---
+sidebar_position: 0
+---
+
+# 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
+
+import { ShowcaseList } from '@site/src/components/ShowcaseList';
+
+<ShowcaseList />

package/docs/en/community/team.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_position: 1
+---
+
+# 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:
+
+import { RandomMemberList } from '@site/src/components/RandomMemberList';
+
+<RandomMemberList />
+
+## All Contributors
+
+Thanks to the following friends for their contributions to Modern.js:
+
+<a
+  href="https://github.com/web-infra-dev/modern.js/graphs/contributors"
+  style={{ display: 'block', marginTop: 24 }}
+>
+  <img
+    src="https://opencollective.com/modernjs/contributors.svg?width=890&button=false"
+    alt="contributors"
+  />
+</a>

package/docs/en/components/bff-upload.mdx

@@ -0,0 +1,97 @@
+### BFF Function
+
+First, create the `api/lambda/upload.ts` file:
+
+```ts title="api/lambda/upload.ts"
+export const post = async ({ formData }: { formData: Record<string, any> }) => {
+  console.info('formData:', formData);
+  // do somethings
+  return {
+    data: {
+      code: 0,
+    },
+  };
+};
+```
+
+:::tip
+The `formData` parameter in the interface processing function can access files uploaded from the client side. It is an `Object` where the keys correspond to the field names used during the upload.
+:::
+
+### Integrated Calling
+
+Next, directly import and call the function in `src/routes/upload/page.tsx`:
+
+```tsx title="routes/upload/page.tsx"
+import { post } from '@api/upload';
+import React, { type JSX } from 'react';
+
+export default (): JSX.Element => {
+  const [file, setFile] = React.useState<FileList | null>();
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setFile(e.target.files);
+  };
+
+  const handleSubmit = async (e: React.MouseEvent<HTMLButtonElement>) => {
+    e.preventDefault();
+    const formData = new FormData();
+    if (file) {
+      for (let i = 0; i < file.length; i++) {
+        formData.append('images', file[i]);
+      }
+      post({
+        formData,
+      });
+    }
+  };
+
+  return (
+    <div>
+      <input multiple type="file" onChange={handleChange} />
+      <button onClick={handleSubmit}>upload</button>
+    </div>
+  );
+};
+```
+
+:::tip
+Note: The input parameter type must be `{ formData: FormData }` for the upload to succeed.
+:::
+
+### Manual Calling
+
+You can manually upload files using the `fetch API`, when calling `fetch`, set the `body` as `FormData` type and submit a post request.
+
+```tsx title="routes/upload/page.tsx"
+import React from 'react';
+
+export default (): JSX.Element => {
+  const [file, setFile] = React.useState<FileList | null>();
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setFile(e.target.files);
+  };
+
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData();
+    if (file) {
+      for (let i = 0; i < file.length; i++) {
+        formData.append('images', file[i]);
+      }
+      await fetch('/api/upload', {
+        method: 'POST',
+        body: formData,
+      });
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input multiple type="file" onChange={handleChange} />
+      <button type="submit">upload</button>
+    </form>
+  );
+};
+```

package/docs/en/components/build-output.mdx

@@ -0,0 +1,45 @@
+To build the production artifacts of the project, run `pnpm run build` in the project:
+
+```bash
+$ pnpm run build
+
+> modern build
+
+  Modern.js Framework
+
+info    Starting production build...
+info    Type checker is enabled. It may take some time.
+ready   Client compiled in 6.19 s
+info    Production file sizes:
+
+  File                                       Size        Gzipped
+  dist/routes-manifest.json                  0.74 kB     0.28 kB
+  dist/static/css/async/page.d7915515.css    1.4 kB      0.69 kB
+  dist/static/js/main.5ae469e7.js            3.0 kB      1.3 kB
+  dist/html/index/index.html                  6.0 kB      2.6 kB
+  dist/static/js/async/page.ddc8a4c1.js      19.2 kB     6.7 kB
+  dist/static/js/34.171fffdb.js              21.3 kB     7.1 kB
+  dist/static/js/lib-router.8995a55e.js      55.3 kB     18.1 kB
+  dist/static/js/lib-lodash.53ec3384.js      71.4 kB     24.8 kB
+  dist/static/js/lib-react.b5856db9.js       140.0 kB    45.2 kB
+  dist/static/js/lib-polyfill.86c452b3.js    213.3 kB    69.9 kB
+
+  Total size:  531.8 kB
+  Gzipped size:  176.7 kB
+```
+
+By default, the build artifacts are generated in `dist/`, with the following directory structure:
+
+```
+dist
+├── html
+│   └── index
+├── modern.config.json
+├── route.json
+├── routes-manifest.json
+└── static
+    ├── css
+    └── js
+```
+
+> If you need to customize the directory of the build artifacts, please refer to [Output files](/guides/basic-features/output-files).

package/docs/en/components/bundler.mdx

@@ -0,0 +1,3 @@
+Refers to module bundlers such as [Rspack](https://rspack.rs/).
+
+The main goal of bundlers is to bundle JavaScript, CSS and other files together, and the bundled files can be used in the browser, Node.js or other environments. When bundler processes the Web application, it builds a dependency graph and then combines every module into one or more bundles.

package/docs/en/components/debug-app.mdx

@@ -0,0 +1,15 @@
+Run `pnpm run dev` in the project to start the project:
+
+```bash
+$ pnpm run dev
+> modern dev
+
+  Modern.js Framework
+
+ready   Client compiled in 0.86 s
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+Open `http://localhost:8080/` in your browser to see the page content.

package/docs/en/components/default-browserslist.mdx

@@ -0,0 +1,7 @@
+
+```yaml title=".browserslistrc"
+chrome >= 87
+edge >= 88
+firefox >= 78
+safari >= 14
+```

package/docs/en/components/deploy-command.mdx

@@ -0,0 +1,14 @@
+## modern deploy
+
+The `modern deploy` command is used to generate artifacts required for the deployment platform.
+
+```bash
+Usage: modern deploy [options]
+
+Options:
+  -c --config <config>  Specify configuration file path, either relative or absolute
+  -s --skip-build       Skip the build stage
+  -h, --help            Display command help
+```
+
+For more details, refer to [Deploy Application](/guides/basic-features/deploy).

package/docs/en/components/deploy.mdx

@@ -0,0 +1 @@
+After local develop, you can refer to the [Deployment](/guides/basic-features/deploy.html) section to deploy the project to the server.

package/docs/en/components/enable-bff-caution.mdx

@@ -0,0 +1,3 @@
+:::tip
+Please refer to the [Enable BFF](/en/guides/advanced-features/bff/function.html#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::

package/docs/en/components/enable-bff.mdx

@@ -0,0 +1,56 @@
+To enable BFF functionality in a Modern.js project, follow these steps to modify the code:
+
+1. Install BFF plugin dependencies
+
+If the BFF plugin is not yet installed in your project, install it first:
+
+```bash
+pnpm add @modern-js/plugin-bff
+```
+
+:::tip Version Consistency
+Make sure the version of `@modern-js/plugin-bff` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+
+Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/plugin-bff`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/plugin-bff
+pnpm add @modern-js/plugin-bff@<version>
+```
+
+:::
+
+2. Configure `modern.config.ts`
+
+Import and add the BFF plugin in the `modern.config.ts` file:
+
+```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff';
+
+export default defineConfig({
+  plugins: [appTools(), bffPlugin()],
+});
+```
+
+3. Configure TypeScript alias
+
+To correctly recognize the `@api` alias in TypeScript, it is recommended to add path mapping in `tsconfig.json`:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      ..., // other paths,
+      "@api/*": ["./api/lambda/*"]
+    }
+  },
+  "include": [
+    ..., // other include directories
+    "api"  // Add api directory
+  ]
+}
+```

package/docs/en/components/enable-ssg.mdx

@@ -0,0 +1,49 @@
+To enable SSG functionality in a Modern.js project, follow these steps to modify the code:
+
+1. Install SSG plugin dependencies
+
+If the SSG plugin is not yet installed in your project, install it first:
+
+```bash
+pnpm add @modern-js/plugin-ssg
+```
+
+:::tip Version Consistency
+
+Make sure the version of `@modern-js/plugin-ssg` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+
+Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/plugin-ssg`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/plugin-ssg
+pnpm add @modern-js/plugin-ssg@<version>
+```
+
+:::
+
+2. Configure modern.config.ts
+
+Import and add the SSG plugin in the `modern.config.ts` file, and configure `output.ssg`:
+
+```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
+import { ssgPlugin } from '@modern-js/plugin-ssg';
+
+export default defineConfig({
+  plugins: [appTools(), ssgPlugin()],
+  output: {
+    ssg: true,
+  },
+});
+```
+
+:::info Scope of Application
+
+- Use `output.ssg` for single-entry apps.
+- Use `output.ssgByEntries` for multi-entry apps.
+- When only `output.ssg: true` is set and `output.ssgByEntries` is not configured, all routes under all entries will be treated as SSG routes.
+
+:::

package/docs/en/components/entry-scan-logic.mdx

@@ -0,0 +1,7 @@
+:::tip Entry scanning logic
+- If `src/` itself meets entry criteria → Single-entry application
+- If `src/` does not meet criteria → Scan subdirectories under `src/` → Multi-entry application
+- In single-entry applications, the default entry name is `index`
+
+:::
+

package/docs/en/components/extend-bff-function.mdx

@@ -0,0 +1,3 @@
+The standard BFF function writing method may not always meet your needs. For example, complex TS type requirements in business scenarios. Modern.js provides a more powerful BFF function writing method.
+
+For more details, please refer to - [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators).