@modern-js/main-doc 2.64.2 → 2.65.0

package/docs/en/components/create-bff-api-app.mdx

@@ -0,0 +1,25 @@
+1. run `@modern-js/create` command：
+
+```bash
+npx @modern-js/create@latest myapi
+```
+
+2. interactive Q & A interface to initialize the project based on the results, with initialization performed according to the default settings:
+
+```bash
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+```
+
+3. Execute the `new` command，enable BFF:
+
+```bash
+? Please select the operation you want to perform Enable optional features
+? Please select the feature to enable Enable "BFF"
+? Please select BFF type Framework mode
+```
+
+
+4. Execute【[Existing BFF-enabled Projects](/en/guides/advanced-features/bff/cross-project.html#existing-bff-enabled-projects)】to turn on the cross-project call switch.
+
+**Note:** When a project serves solely as a BFF producer, its runtime does not depend on the `/src` source directory. Removing the `/src` directory can help optimize the project's build efficiency.

package/docs/en/configure/app/performance/build-cache.mdx

@@ -1,5 +1,6 @@
 ---
 title: buildCache
+configName: performance.buildCache
 ---
 
 # performance.buildCache
@@ -17,37 +18,18 @@ type BuildCacheConfig =
        * Set different cache names based on cacheDigest content.
        */
       cacheDigest?: Array<string | undefined>;
+      /**
+       * An arrays of additional code dependencies for the build.
+       * Rspack / webpack will use a hash of each of these items and all dependencies to invalidate the filesystem cache.
+       */
+      buildDependencies?: string[];
     }
   | boolean;
 ```
 
-- **Default:**
-
-```js
-const defaultBuildCacheConfig = {
-  cacheDirectory: './node_modules/.cache/webpack',
-};
-```
-
-- **Bundler:** `only support webpack`
-
 Controls the caching behavior during the build process.
 
-Modern.js will enable build cache by default to improve the compile speed, the generated cache files are write to the `./node_modules/.cache/webpack` directory by default.
-
-You can configure the cache path with `buildCache`, e.g.
-
-```js
-export default {
-  performance: {
-    buildCache: {
-      cacheDirectory: './node_modules/.custom_cache/webpack',
-    },
-  },
-};
-```
-
-You can also disable the build cache by setting it to `false`:
+When you are using webpack as build tool, Modern.js will enable build cache by default to improve the compile speed. You can disable the build cache by setting it to `false`:
 
 ```js
 export default {
@@ -57,29 +39,8 @@ export default {
 };
 ```
 
-### cacheDigest
-
-`cacheDigest` is used to add some environment variables that will affect the build results. Modern.js will set the cache name based on the `cacheDigest` content and the current build mode to ensure that different cacheDigests can hit different caches.
+It should be noted that, Rspack's persistent cache is [experimental](https://rspack.dev/config/experiments#experimentscache), which may change in future versions, and this feature needs to be turned on manually.
 
-#### Example
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
 
-The current project needs to set different extensions according to different `APP_ID`. By default, since the code & configuration & dependencies of the current project have not changed, the previous cache will be hit.
-
-By adding `APP_ID` to `cacheDigest`, different cache results will be searched when APP_ID changes, thereby avoiding hitting cache results that do not meet expectations.
-
-```js
-export default {
-  tools: {
-    bundlerChain: (chain: any) => {
-      if (process.env.APP_ID === 'xxx') {
-        chain.resolve.extensions.prepend('.ttp.ts');
-      }
-    },
-  },
-  performance: {
-    buildCache: {
-      cacheDigest: [process.env.APP_ID],
-    },
-  },
-};
-```
+<RsbuildConig />

package/docs/en/guides/advanced-features/bff/_meta.json

@@ -1 +1 @@
-["function", "frameworks", "extend-server", "sdk", "upload"]
+["function", "frameworks", "extend-server", "sdk", "upload", "cross-project"]

package/docs/en/guides/advanced-features/bff/cross-project.mdx

@@ -0,0 +1,116 @@
+import { PackageManagerTabs } from '@theme';
+
+# Cross-Project Invocation
+
+Based on the BFF architecture, Modern.js provides cross-project invocation capabilities, allowing BFF functions created in one project to be invoked by other projects through integrated calls, enabling function sharing and feature reuse across projects.
+Cross-project invocation consists of **producer** and **consumer** sides. The producer is responsible for creating and providing BFF services while generating integrated invocation SDK, and the consumer initiates requests through these SDK.
+
+## BFF Producer
+
+Upgrade Modern.js dependencies to version x.64.4 or higher, then enable cross-project invocation via configuration. Projects with BFF capabilities enabled can act as BFF producers, or you can create standalone BFF applications.
+When executing `dev` or `build`, the following artifacts for consumers will be automatically generated:
+- API functions under the `dist/client` directory
+- Runtime configuration functions under the `dist/runtime` directory
+- Interface exports defined in `exports` field of `package.json`
+- File list for npm publication specified in `files` field of `package.json`
+
+### Existing BFF-enabled Projects
+
+1. Enable Cross-Project Invocation
+
+Ensure the current project has BFF enabled with API files defined under `api/lambda`. Add the following configuration:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  }
+});
+```
+
+2. Generate SDK Type Files
+
+To provide type hints for the integrated invocation SDK, enable the `declaration` option in TypeScript configuration:
+
+```ts title="tsconfig.json"
+"compilerOptions": {
+    "declaration": true,
+}
+```
+
+### Create BFF Application
+
+import CreateApi from "@site-docs-en/components/create-bff-api-app"
+
+<CreateApi/>
+
+## BFF Consumer
+
+:::info
+You can initiate requests to BFF producers from projects using any framework via the SDK.
+:::
+
+### Intra-Monorepo Invocation
+
+When producer and consumer are in the same Monorepo, directly import the SDK. API functions reside under `${package_name}/api`:
+
+```ts title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '${package_name}/api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    hello().then(setText);
+  }, []);
+  return <div>{text}</div>;
+};
+```
+
+### Cross-Project Invocation
+
+When producer and consumer are in separate repositories, publish the BFF producer as an npm package. The invocation method remains the same as intra-Monorepo.
+
+### Domain Configuration and Extensions
+
+For real-world scenarios requiring custom BFF service domains, use the configuration function:
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+
+configure({
+  setDomain() {
+    return 'https://your-bff-api.com';
+  },
+});
+```
+
+The `configure` function from `${package_name}/runtime` supports domain configuration via `setDomain`, interceptors, and custom SDK. When extending both **current project** and **cross-project** SDK on the same page:
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+import { configure as innerConfigure } from '@modern-js/runtime/bff';
+import axios from 'axios';
+
+configure({
+    setDomain() {
+        return 'https://your-bff-api.com';
+    },
+});
+
+innerConfigure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string,
+      method: params?.method as Method,
+      data: params?.body,
+      headers: {
+        'x-header': 'innerConfigure',
+      },
+    });
+    return res.data;
+  },
+});
+```

package/docs/zh/components/create-bff-api-app.mdx

@@ -0,0 +1,25 @@
+
+1. 执行 `@modern-js/create` 命令：
+
+```bash
+npx @modern-js/create@latest myapi
+```
+
+2. 可交互的问答界面中，按照默认的选择进行初始化:
+
+```bash
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+
+3. 执行 `new` 命令，启用 BFF:
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 请选择功能名称 启用「BFF」功能
+? 请选择 BFF 类型 框架模式
+```
+
+
+4. 执行【[已启用 BFF 的项目](/guides/advanced-features/bff/cross-project.html#已启用-bff-的项目)】步骤，即可打开跨项目调用开关。
+需要注意的是，当项目仅作为 BFF 生产端，其运行时不依赖 `/src` 源码目录。因此，移除 `/src` 目录可在一定程度上优化工程的编译效率。

package/docs/zh/configure/app/performance/build-cache.mdx

@@ -1,5 +1,6 @@
 ---
 title: buildCache
+configName: performance.buildCache
 ---
 
 # performance.buildCache
@@ -10,44 +11,25 @@ title: buildCache
 type BuildCacheConfig =
   | {
       /**
-       * webpack 文件缓存系统的缓存目录
+       * 用于设置缓存文件的输出目录
        */
       cacheDirectory?: string;
       /**
        * 根据 cacheDigest 内容设置不同的缓存名称
        */
       cacheDigest?: Array<string | undefined>;
+      /**
+       * 一个包含构建依赖的文件数组。
+       * Rspack / webpack 将使用其中每个文件的哈希值来判断持久化缓存是否失效。
+       */
+      buildDependencies?: string[];
     }
   | boolean;
 ```
 
-- **默认值：**
-
-```js
-const defaultBuildCacheConfig = {
-  cacheDirectory: './node_modules/.cache/webpack',
-};
-```
-
-- **打包工具：** `仅支持 webpack`
-
 控制 Modern.js 在构建过程中的缓存行为。
 
-Modern.js 默认会开启构建缓存来提升二次构建的速度，并默认把生成的缓存文件写到 `./node_modules/.cache/webpack` 目录下。
-
-你可以通过 `buildCache` 配置缓存路径，比如：
-
-```js
-export default {
-  performance: {
-    buildCache: {
-      cacheDirectory: './node_modules/.custom_cache/webpack',
-    },
-  },
-};
-```
-
-如果不希望缓存，你也可以将 `buildCache` 置为 `false` 将其禁用掉：
+在使用 webpack 构建时，Modern.js 默认会开启构建缓存来提升二次构建的速度。如果不希望缓存，你可以将 `buildCache` 置为 `false` 将其禁用掉：
 
 ```js
 export default {
@@ -57,28 +39,8 @@ export default {
 };
 ```
 
-### cacheDigest
+需要注意的是，Rspack 的持久化缓存处于[实验性阶段](https://rspack.dev/zh/config/experiments#experimentscache)，可能会在未来的版本中发生变化，该功能需要手动开启。
 
-`cacheDigest` 用来添加一些会对构建结果产生影响的环境变量。Modern.js 将根据 `cacheDigest` 内容和当前构建模式来设置缓存名称，来确保不同的 `cacheDigest` 可以命中不同的缓存。
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
 
-#### 示例
-
-当前项目需要根据不同的 `APP_ID` 来设置不同的 extensions。默认情况下，由于当前项目的代码 & 配置 & 依赖未发生变化，会命中之前的缓存。
-通过将 `APP_ID` 添加到 `cacheDigest` 中，在 `APP_ID` 变化时会去查找不同的缓存结果，从而避免命中不符合预期的缓存结果。
-
-```js
-export default {
-  tools: {
-    bundlerChain: chain => {
-      if (process.env.APP_ID === 'xxx') {
-        chain.resolve.extensions.prepend('.ttp.ts');
-      }
-    },
-  },
-  performance: {
-    buildCache: {
-      cacheDigest: [process.env.APP_ID],
-    },
-  },
-};
-```
+<RsbuildConig />

package/docs/zh/guides/advanced-features/bff/_meta.json

@@ -1 +1 @@
-["function", "frameworks", "extend-server", "sdk", "upload"]
+["function", "frameworks", "extend-server", "sdk", "upload", "cross-project"]

package/docs/zh/guides/advanced-features/bff/cross-project.mdx

@@ -0,0 +1,120 @@
+import { PackageManagerTabs } from '@theme';
+
+# 跨项目调用
+
+基于 BFF 架构，Modern.js 提供了跨项目调用的能力，即在一个项目中创建的 BFF 函数可以被其他项目进行一体化调用，实现项目间的函数共享和功能复用。
+跨项目调用分为 BFF 的**生产端**和**消费端**。生产端负责创建和提供 BFF 服务、生成一体化调用 SDK，而消费端通过调用 SDK 发起接口请求。
+
+## BFF 生产端
+
+升级 Modern.js 相关依赖到 x.64.4 及以上版本，通过配置即可启用跨项目调用能力。你可以将已启用 BFF 能力的项目视为 BFF 生产端，也可以单独创建独立的 BFF 应用。
+当执行 `dev` 或 `build`，都会自动生成供消费端使用的产物，包括：
+- `dist/client` 目录下的接口函数
+- `dist/runtime` 目录下的运行时配置函数
+- `package.json` 中 `exports` 定义接口函数出口
+- `package.json` 中 `files` 指定发布到 npm 包的文件列表
+
+### 已启用 BFF 的项目
+
+1. 开启跨项目调用
+
+确保当前项目已启动 BFF 能力，并在 `api/lambda` 目录下定义接口文件。完成如下配置：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  }
+});
+```
+
+
+2. 生成 SDK 类型文件
+
+为一体化调用 SDK 提供类型提示，需要在 `TypeScript` 的 `tsconfig.json` 文件中打开 `declaration` 选项，配置如下：
+
+```ts title="tsconfig.json"
+"compilerOptions": {
+    "declaration": true,
+}
+```
+
+### 创建 BFF 应用
+
+import CreateApi from "@site-docs/components/create-bff-api-app"
+
+<CreateApi/>
+
+## BFF 消费端
+
+:::info
+你可以在任意框架的项目中通过调用 SDK 向 BFF 生产端发起接口请求。
+:::
+
+### 同一 Monorepo 内调用
+
+如果生产端和消费端在同一 Monorepo 中，可以直接引入 SDK。接口函数位于 `${package_name}/api` 目录下，示例如下：
+
+```ts title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '${package_name}/api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    hello().then(setText);
+  }, []);
+  return <div>{text}</div>;
+};
+```
+
+### 独立项目间调用
+
+当生产端和消费端不在同一个 Monorepo 中时，生产端需要通过 `npm publish` 将 BFF 生产端项目发布为包，调用方式与 Monorepo 内相同。
+
+### 配置域名及扩展功能
+
+实际应用场景中，跨项目调用需要指定 BFF 服务的域名。可以通过以下配置函数实现：
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+
+configure({
+  setDomain() {
+    return 'https://your-bff-api.com';
+  },
+});
+```
+
+`${package_name}/runtime` 目录下的 `configure` 函数，支持通过 `setDomain` 配置域名，`configure` 同样支持添加拦截器和自定义请求 SDK 能力。
+当需要在同一页面中同时对**当前项目**和**跨项目**的一体化调用 SDK 进行扩展，建议采用以下配置：
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+import { configure as innerConfigure } from '@modern-js/runtime/bff';
+import axios from 'axios';
+
+configure({
+    setDomain() {
+        return 'https://your-bff-api.com';
+    },
+});
+
+innerConfigure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string,
+      method: params?.method as Method,
+      data: params?.body,
+      headers: {
+        'x-header': 'innerConfigure',
+      },
+    });
+    return res.data;
+  },
+});
+
+
+```

package/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.64.2",
+  "version": "2.65.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.64.2"
+    "@modern-js/sandpack-react": "2.65.0"
   },
   "devDependencies": {
     "@rspress/shared": "1.40.2",