@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.97 → 3.5.0-ultramodern.99

package/docs/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/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/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/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/components/default-browserslist.mdx

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

package/docs/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/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/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/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/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/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/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).

package/docs/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/components/init-app.mdx

@@ -0,0 +1,93 @@
+UltraModern.js provides the BleedingDev create package to create SuperApp
+workspaces. It does not require global installation and can be run on-demand
+using `pnpm dlx`.
+
+The supported pnpm command is the scoped package specifier:
+`pnpm dlx @bleedingdev/modern-js-create <target>`. Do not shorten it to
+`pnpm dlx modern-js-create`; there is no unscoped package by that name.
+
+You can initialize the empty directory you are already in:
+
+```bash
+mkdir myapp && cd myapp
+pnpm dlx @bleedingdev/modern-js-create .
+```
+
+You can also create a project directly in a new directory:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app
+```
+
+To initialize with workspace protocol dependencies (for local monorepo testing of unreleased Modern.js packages):
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app --workspace
+```
+
+The BleedingDev create package will directly create the application without providing an interactive Q & A interface:
+
+```bash
+🚀 Welcome to UltraModern.js
+
+📦 Creating project "my-super-app"...
+
+✨ Project created successfully! 🎉
+
+📋 Next, you can run the following commands:
+
+📁 Enter the project directory:
+
+  cd my-super-app
+
+🔧 Initialize Git repository:
+
+  git init
+
+📥 Install project dependencies:
+
+  pnpm install
+
+⚡ Start the development server:
+
+  pnpm start
+```
+
+Now, the project structure is as follows:
+
+```
+.
+├── apps
+│   └── shell-super-app
+├── package.json
+├── packages
+│   ├── shared-contracts
+│   ├── shared-design-tokens
+│   └── shared-effect-client
+├── scripts
+├── topology
+└── verticals
+```
+
+The default workspace starts shell-only and installs the published BleedingDev
+package aliases:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app
+```
+
+From a generated SuperApp workspace, add a business MicroVertical in place:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
+```
+
+The `--vertical` command mutates the current workspace: it adds the vertical
+package and wires topology, ownership metadata, shell Module Federation,
+development overlays, package dependencies, generated contracts, route-owned
+i18n, CSS isolation, and the Effect BFF/client surface.
+
+The lower-level `--ultramodern-package-*` flags are reserved for release
+engineering and local package-source testing. BleedingDev packages are published
+through GitHub Actions trusted publishing; do not publish them manually from a
+developer machine.

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

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

package/docs/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/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/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/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/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/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/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/components/language-config.mdx

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

package/docs/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.