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

package/docs/en/components/hono.mdx

@@ -0,0 +1,120 @@
+### Getting Request Context
+
+Sometimes in BFF functions, it's necessary to obtain the request context to handle more logic. In such cases, you can use `useHonoContext` to get it:
+
+```ts title="api/lambda/hello.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+
+export const get = async () => {
+  const c = useHonoContext();
+  console.info(`access url: ${c.req.url}`);
+  return 'Hello Modern.js';
+};
+```
+
+:::info
+For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-backend-context).
+:::
+
+### Getting Cookies
+
+When getting cookies in BFF functions, you need to get the request context through `useHonoContext`, then use `c.req.header('cookie')` to get the Cookie string and parse it manually:
+
+```ts title="api/lambda/cookies.ts"
+import { Api, Get } from '@modern-js/plugin-bff/hono-server';
+import { useHonoContext } from '@modern-js/server-runtime';
+
+// Helper function to parse Cookie string
+function parseCookies(
+  cookieHeader: string | undefined,
+): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  if (!cookieHeader) return cookies;
+
+  cookieHeader.split(';').forEach(cookie => {
+    const [name, ...rest] = cookie.trim().split('=');
+    if (name) {
+      cookies[name] = rest.join('=');
+    }
+  });
+
+  return cookies;
+}
+
+export const getCookies = Api(Get('/cookies'), async () => {
+  const c = useHonoContext();
+  const cookieHeader = c.req.header('cookie');
+  const cookies = parseCookies(cookieHeader);
+  const token = cookies.token;
+  const sessionId = cookies.sessionId;
+  return {
+    hasToken: !!token,
+    token: token || null,
+    sessionId: sessionId || null,
+  };
+});
+```
+
+:::caution Note
+The `c.req.cookie()` method does not exist in the current version. You need to use `c.req.header('cookie')` to get the Cookie string and parse it manually.
+:::
+
+### Defining BFF Functions
+
+When using Hono as the runtime framework, you can define interfaces through [Api functions](/guides/advanced-features/bff/operators.html):
+
+```ts title="api/lambda/user.ts"
+import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { z } from 'zod';
+
+const QuerySchema = z.object({
+  id: z.string(),
+});
+
+export const getUser = Api(
+  Get('/user'),
+  Query(QuerySchema),
+  async ({ query }) => {
+    return {
+      id: query.id,
+      name: 'Modern.js',
+      email: 'modernjs@bytedance.com',
+    };
+  },
+);
+```
+
+:::info
+For more details about Api functions and operators, refer to [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators.html).
+:::
+
+### Using Middleware
+
+Hono supports a rich middleware ecosystem, and you can use middleware in BFF functions:
+
+```ts title="api/lambda/user.ts"
+import { Api, Get, Middleware } from '@modern-js/plugin-bff/hono-server';
+
+export const getUser = Api(
+  Get('/user'),
+  Middleware(async (c, next) => {
+    // You can access Hono's Context in middleware
+    c.res.headers.set('X-Powered-By', 'Modern.js');
+    await next();
+  }),
+  async () => {
+    return {
+      name: 'Modern.js',
+      email: 'modernjs@bytedance.com',
+    };
+  },
+);
+```
+
+:::info
+For more details about middleware, refer to [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators.html#middleware).
+:::
+
+### More Hono Documentation
+
+For more detailed information about Hono, please refer to the [Hono official documentation](https://hono.dev/).

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

@@ -0,0 +1,111 @@
+Modern.js provides the `@modern-js/create` tool to create projects. It does not require global installation and can be run on-demand using `npx`.
+
+You can create a project in an existing empty directory:
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create@latest
+```
+
+You can also create a project directly in a new directory:
+
+```bash
+npx @modern-js/create@latest myapp
+```
+
+To initialize a TanStack Router template:
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack
+```
+
+To initialize with Tailwind CSS v4 scaffold:
+
+```bash
+npx @modern-js/create@latest myapp --tailwind
+```
+
+To initialize TanStack Router with Tailwind CSS v4:
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack --tailwind
+```
+
+To initialize BFF scaffold with the current default runtime:
+
+```bash
+npx @modern-js/create@latest myapp --bff
+```
+
+To initialize BFF scaffold with Effect HttpApi runtime:
+
+```bash
+npx @modern-js/create@latest myapp --bff-runtime effect
+```
+
+To initialize BFF scaffold with Hono runtime:
+
+```bash
+npx @modern-js/create@latest myapp --bff-runtime hono
+```
+
+To initialize with workspace protocol dependencies (for local monorepo testing of unreleased Modern.js packages):
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --workspace
+```
+
+`@modern-js/create` will directly create the application without providing an interactive Q & A interface:
+
+```bash
+🚀 Welcome to Modern.js
+
+📦 Creating project "myapp"...
+
+✨ Project created successfully! 🎉
+
+📋 Next, you can run the following commands:
+
+📁 Enter the project directory:
+
+  cd myapp
+
+🔧 Initialize Git repository:
+
+  git init
+
+📥 Install project dependencies:
+
+  pnpm install
+
+⚡ Start the development server:
+
+  pnpm start
+```
+
+Now, the project structure is as follows:
+
+```
+.
+├── biome.json
+├── modern.config.ts
+├── package.json
+├── README.md
+├── src
+│   ├── modern-app-env.d.ts
+│   ├── modern.runtime.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+└── tsconfig.json
+```
+
+When `--tailwind` is enabled, `postcss.config.mjs` and `tailwind.config.ts` are generated in the project root.
+
+When `--bff` or `--bff-runtime effect` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/effect/index.ts` + `shared/effect/api.ts`, and sets `bff.runtimeFramework` to `effect`.
+When `--bff-runtime hono` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/lambda/hello.ts`, and sets `bff.runtimeFramework` to `hono`.
+When `--workspace` is enabled, `@modern-js/*` dependencies use `workspace:*` versions for local monorepo linkage.
+
+If you want the public opinionated UltraModern path, start from the generated
+`presetUltramodern(...)` scaffold and then choose the runtime lane explicitly.

package/docs/en/components/init-rspack-app.mdx

@@ -0,0 +1,5 @@
+```bash
+$ npx @modern-js/create@latest myapp
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+```

package/docs/en/components/internal-logger.mdx

@@ -0,0 +1,25 @@
+In Modern.js, log events are handled by `LoggerMonitor`, which outputs logs to the console.
+
+:::info
+The built-in `LoggerMonitor` depends on the [rslog](https://www.npmjs.com/package/rslog) library.
+:::
+
+For example, intentionally throwing an error in the project:
+
+```tsx title=routes/page.tsx
+import './index.css';
+
+const Index = () => <div className="container-box">{a}</div>;
+
+export default Index;
+```
+
+If running normally, you can see the following output in the console:
+
+```shell
+> Local:    http://localhost:8080/
+> press h + enter to show shortcuts
+
+error   SSR Error - App Prerender, error = ReferenceError: a is not defined
+    at Index (/somepath/page.tsx:3:1)
+```

package/docs/en/components/internal-metrics.mdx

@@ -0,0 +1,20 @@
+In Modern.js, metric events are also handled by `LoggerMonitor`, which outputs metrics to the console in a specific format.
+
+:::info
+The built-in `LoggerMonitor` depends on the [rslog](https://www.npmjs.com/package/rslog) library.
+:::
+
+The `rslog` instance initialized in Modern.js outputs logs at `debug` level and above in development environment by default, and outputs all logs in production environment. In the built-in `LoggerMonitor`, all metric events are output as Debug logs. Therefore, if you want to view metric event information in the development environment, you need to add additional environment variables.
+
+Developers can add the environment variable `DEBUG=true` when running the `dev` command. If running normally, after accessing, you can see the following output in the console:
+
+```shell
+> Local:    http://localhost:8080/
+> press h + enter to show shortcuts
+
+debug   SSR Debug - server-loader, cost: 2.000094, req.url = /
+debug   SSR Debug - ssr-prerender, cost: 6.99997, req.url = /
+debug   SSR Debug - ssr-render-html, cost: 0.999927, req.url = /
+debug   Debug - server-handle-request, cost: 19.999981, req.url = /
+debug     --> GET / 200 90ms
+```

package/docs/en/components/international/custom-instance-code.mdx

@@ -0,0 +1,16 @@
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// Create custom instance
+const customI18n = i18next.createInstance({
+  // Custom configuration
+});
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+  },
+});
+```
+

package/docs/en/components/international/init-options-desc.mdx

@@ -0,0 +1 @@
+All [i18next initialization options](https://www.i18next.com/overview/configuration-options) are supported. Common options are described below:

package/docs/en/components/international/install-command.mdx

@@ -0,0 +1,10 @@
+`i18next` and `react-i18next` are **Peer Dependencies** and must be installed manually.
+
+:::note Version consistency
+`@modern-js/plugin-i18n` should use the same version as `@modern-js/app-tools` in your project.
+:::
+
+```bash
+pnpm list @modern-js/app-tools
+pnpm add @modern-js/plugin-i18n@<version> i18next react-i18next
+```

package/docs/en/components/international/instance-code.mdx

@@ -0,0 +1,16 @@
+Create `src/modern.runtime.ts`:
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// i18next exports a global singleton by default, which can cause multiple apps to affect each other.
+// createInstance() creates an isolated instance so each app has independent language state.
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,
+  },
+});
+```

package/docs/en/components/international/introduce.mdx

@@ -0,0 +1,5 @@
+`@modern-js/plugin-i18n` is the internationalization plugin for Modern.js, built on [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/).
+
+- **The plugin itself**: Integrates with the Modern.js framework, including SSR language passing, route prefix handling, and more.
+- **i18next**: Provides core translation capabilities, such as the `t()` function, interpolation, plurals, and namespaces.
+- **react-i18next**: Provides React components and Hooks, such as `useTranslation`, to integrate translations with the React lifecycle.

package/docs/en/components/language-config.mdx

@@ -0,0 +1,9 @@
+### language
+
+Question: Please select the programming language.
+
+Options:
+
+- TS -- ts
+
+- ES6+ -- js

package/docs/en/components/micro-frontend.mdx

@@ -0,0 +1,6 @@
+Micro-frontend (MFE) is an architecture style similar to microservices. It is a composition of multiple independently delivered frontend applications, forming a cohesive whole. MFE decomposes frontend applications into smaller, simpler applications that can be developed, tested, and deployed independently while still appearing as a cohesive single product to users.
+
+It primarily addresses two problems:
+
+- Difficulty in maintaining large and complex applications as they evolve over time.
+- Inefficiency caused by cross-team or cross-department collaboration in project development.

package/docs/en/components/micro-master-manifest-config.mdx

@@ -0,0 +1,15 @@
+## manifest
+
+```ts
+interface Manifest {
+  getAppList?: () => Array<AppInfo>;
+}
+```
+
+### getAppList?
+
+Through the `getAppList` configuration, you can customize how to get remote list data
+
+```ts
+type GetAppList = () => Promise<Array<AppInfo>>;
+```

package/docs/en/components/micro-runtime-config.mdx

@@ -0,0 +1,17 @@
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [{
+      name: 'Table',
+      entry: 'http://localhost:8081',
+      // activeWhen: '/table'
+    }, {
+      name: 'Dashboard',
+      entry: 'http://localhost:8082'
+      // activeWhen: '/dashboard'
+    }]
+  },
+});
+```

package/docs/en/components/module-federation.mdx

@@ -0,0 +1,7 @@
+Module Federation (MF) is a technology solution that allows multiple JavaScript applications to share code and resources. Similar to microservices architecture on the server side, it allows you to split large applications into multiple independent smaller applications that can be developed, tested, and deployed independently, while dynamically loading modules from other applications at runtime.
+
+Module Federation solves the problem of code duplication across multiple frontend applications. In the traditional approach, if multiple applications need to use the same components or utility functions, you would need to duplicate this code in each application, leading to code duplication, high maintenance costs, and larger application sizes. With Module Federation, you can place common code in one application and have other applications load it dynamically as needed, enabling code sharing and reducing duplication.
+
+Module Federation 2.0 supports [Rspack](https://rspack.rs/) build tools, and provides enhanced features such as dynamic type hints, Manifest, Federation Runtime, runtime plugin system, and Chrome Devtools support for better development experience and debugging capabilities. You can visit the [Module Federation official documentation](https://module-federation.io/) to learn more.
+
+Modern.js provides an example project for Module Federation. Please refer to [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs).

package/docs/en/components/nodeVersion.mdx

@@ -0,0 +1,28 @@
+Before getting started, you will need to install [Node.js](https://nodejs.org/), and ensure that your Node.js version is not lower than v20.19.5. **We recommend using the LTS version of Node.js 22.**
+
+You can check the currently used Node.js version with the following command:
+
+```bash
+node -v
+```
+
+If you do not have Node.js installed in your current environment, or the installed version is lower than v20.19.5, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install the required version.
+
+Here is an example of how to install the Node.js 22 LTS version via nvm:
+
+```bash
+# Install the long-term support 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
+```
+
+:::tip nvm and fnm
+Both nvm and fnm are Node.js version management tools. Relatively speaking, nvm is more mature and stable, while fnm is implemented using Rust, which provides better performance than nvm.
+:::
+
+Additionally, after installing nvm or fnm, when there is a `.nvmrc` file containing `lts/jod` in the repository's root directory, the system will automatically install or switch to the correct Node.js version upon entering the repository.

package/docs/en/components/output-polyfill-extend.mdx

@@ -0,0 +1 @@
+Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information. For detailed usage instructions, please refer to [Polyfill At Runtime](https://modernjs.dev/en/guides/advanced-features/compatibility.html#polyfill-at-runtime).

package/docs/en/components/prerequisites.mdx

@@ -0,0 +1,18 @@
+### Node.js
+
+import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
+
+<NodeVersion />
+
+### pnpm
+
+It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
+
+```bash
+npm install -g pnpm@10
+```
+
+:::note
+Modern.js also supports dependency management with `yarn` and `npm`.
+
+:::

package/docs/en/components/release-note.mdx

@@ -0,0 +1 @@
+According to the [Release Note](https://github.com/web-infra-dev/modern.js/releases) on the official website, developers can also manually upgrade the project to the desired version.

package/docs/en/components/rsbuild-config-tooltip.mdx

@@ -0,0 +1,5 @@
+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={props.configName}/>.
+:::

package/docs/en/components/rsbuild.mdx

@@ -0,0 +1,3 @@
+[Rsbuild](https://v2.rsbuild.rs/) is an Rspack-based build tool for the web. The main goal of Rsbuild is to provide out-of-the-box build capabilities for Rspack users, allowing developers to start a web project with zero configuration.
+
+Rsbuild integrates high-performance Rust-based tools from the community, including Rspack and SWC, to provide first-class build speed and development experience.

package/docs/en/components/rsc-deploy-tip.mdx

@@ -0,0 +1 @@
+

package/docs/en/components/rspack.mdx

@@ -0,0 +1,3 @@
+[Rspack](https://rspack.rs/) is a high performance JavaScript bundler written in Rust. It offers strong compatibility with the webpack ecosystem, allowing for seamless replacement of webpack, and provides lightning fast build speeds.
+
+Compared to webpack, Rspack has significantly improved build performance, thanks not only to the language advantages brought by Rust, but also to its parallel architecture and incremental compilation features. Benchmarking has shown that Rspack can provide 5-10 times better compilation performance.

package/docs/en/components/rspackTip.mdx

@@ -0,0 +1,7 @@
+:::tip Rspack - A High Performance JavaScript Bundler
+
+import Rspack from './rspack.mdx';
+
+<Rspack />
+
+:::

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

@@ -0,0 +1,22 @@
+## modern serve
+
+The `modern serve` command is used to start a Modern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands#modern-build) command beforehand to generate the corresponding artifacts.
+
+```bash
+Usage: modern serve [options]
+
+Options:
+  -c --config <config>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+  --api-only            only run API service
+```
+
+By default, the project will run in `localhost:8080`, you can modify the server port number with `server.port`:
+
+```js
+export default defineConfig({
+  server: {
+    port: 8081,
+  },
+});
+```

package/docs/en/components/ssr-monitor.mdx

@@ -0,0 +1,3 @@
+:::tip
+SSR monitoring has been integrated into the Monitors module, see [Monitors](/guides/advanced-features/server-monitor/monitors) for details.
+:::

package/docs/en/components/swc.mdx

@@ -0,0 +1,3 @@
+[SWC](https://SWC.rs/) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on `Rust`. SWC can provide the same abilities with Babel, and it's more than 10x faster than Babel.
+
+Modern.js has a out-of-box plugin for SWC, power your Web application with Polyfill and minification, we also port some common used Babel plugins to SWC.

package/docs/en/components/tech-stack-node-framework.mdx

@@ -0,0 +1 @@
+Modern.js Server uses [Hono.js](https://hono.dev/) as the server runtime framework. For BFF, `bff.runtimeFramework` defaults to `effect`, while `hono` remains an explicit compatibility runtime. Effect and Hono BFF runtimes are strict modes (no implicit fallback). You can extend the Server based on the Hono.js ecosystem; refer to [Custom Web Server](/guides/advanced-features/web-server.html).

package/docs/en/components/turtorials-example-list.mdx

@@ -0,0 +1,2 @@
+- [Route Authorization](/tutorials/examples/csr-auth.html)
+- ...

package/docs/en/components/ua-polyfill.mdx

@@ -0,0 +1,44 @@
+### Polyfill At Runtime
+
+Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information, which has the following advantages over Babel:
+
+- It will not be inserted into the code, and only delivers Polyfill code on-demand based on the device accessing the page, reducing the overall code size.
+- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster, with overall speed exceeding conventional solutions.
+
+Modern.js provides the `@modern-js/plugin-polyfill` plugin to implement this feature. You can enable it by installing the plugin:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-polyfill',
+    yarn: 'yarn add @modern-js/plugin-polyfill',
+    pnpm: 'pnpm add @modern-js/plugin-polyfill',
+  }}
+/>
+
+Then register the Polyfill plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import { polyfillPlugin } from '@modern-js/plugin-polyfill';
+
+export default defineConfig({
+  plugins: [..., polyfillPlugin()],
+});
+```
+
+After configuring `output.polyfill` as `ua` and executing `pnpm run build && pnpm run serve` to start the server, visiting the page can see that the HTML artifacts contains the following script:
+
+```js
+<script src="/__polyfill__" crossorigin></script>
+```
+
+When accessing the page on Chrome 51, you can see the content returned by `http://localhost:8080/__polyfill__` as follows:
+
+![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
+
+:::caution
+This feature only works when using Modern.js built-in Web Server.
+
+If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through `html.template` or `tools.html` may cause this feature to not work correctly.
+:::