@modern-js/main-doc 2.64.2 → 2.65.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,25 @@
1
+ 1. run `@modern-js/create` command:
2
+
3
+ ```bash
4
+ npx @modern-js/create@latest myapi
5
+ ```
6
+
7
+ 2. interactive Q & A interface to initialize the project based on the results, with initialization performed according to the default settings:
8
+
9
+ ```bash
10
+ ? Please select the programming language: TS
11
+ ? Please select the package manager: pnpm
12
+ ```
13
+
14
+ 3. Execute the `new` command,enable BFF:
15
+
16
+ ```bash
17
+ ? Please select the operation you want to perform Enable optional features
18
+ ? Please select the feature to enable Enable "BFF"
19
+ ? Please select BFF type Framework mode
20
+ ```
21
+
22
+
23
+ 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.
24
+
25
+ **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.
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: buildCache
3
+ configName: performance.buildCache
3
4
  ---
4
5
 
5
6
  # performance.buildCache
@@ -17,37 +18,18 @@ type BuildCacheConfig =
17
18
  * Set different cache names based on cacheDigest content.
18
19
  */
19
20
  cacheDigest?: Array<string | undefined>;
21
+ /**
22
+ * An arrays of additional code dependencies for the build.
23
+ * Rspack / webpack will use a hash of each of these items and all dependencies to invalidate the filesystem cache.
24
+ */
25
+ buildDependencies?: string[];
20
26
  }
21
27
  | boolean;
22
28
  ```
23
29
 
24
- - **Default:**
25
-
26
- ```js
27
- const defaultBuildCacheConfig = {
28
- cacheDirectory: './node_modules/.cache/webpack',
29
- };
30
- ```
31
-
32
- - **Bundler:** `only support webpack`
33
-
34
30
  Controls the caching behavior during the build process.
35
31
 
36
- 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.
37
-
38
- You can configure the cache path with `buildCache`, e.g.
39
-
40
- ```js
41
- export default {
42
- performance: {
43
- buildCache: {
44
- cacheDirectory: './node_modules/.custom_cache/webpack',
45
- },
46
- },
47
- };
48
- ```
49
-
50
- You can also disable the build cache by setting it to `false`:
32
+ 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`:
51
33
 
52
34
  ```js
53
35
  export default {
@@ -57,29 +39,8 @@ export default {
57
39
  };
58
40
  ```
59
41
 
60
- ### cacheDigest
61
-
62
- `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.
42
+ 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.
63
43
 
64
- #### Example
44
+ import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
65
45
 
66
- 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.
67
-
68
- 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.
69
-
70
- ```js
71
- export default {
72
- tools: {
73
- bundlerChain: (chain: any) => {
74
- if (process.env.APP_ID === 'xxx') {
75
- chain.resolve.extensions.prepend('.ttp.ts');
76
- }
77
- },
78
- },
79
- performance: {
80
- buildCache: {
81
- cacheDigest: [process.env.APP_ID],
82
- },
83
- },
84
- };
85
- ```
46
+ <RsbuildConig />
@@ -1 +1 @@
1
- ["function", "frameworks", "extend-server", "sdk", "upload"]
1
+ ["function", "frameworks", "extend-server", "sdk", "upload", "cross-project"]
@@ -0,0 +1,116 @@
1
+ import { PackageManagerTabs } from '@theme';
2
+
3
+ # Cross-Project Invocation
4
+
5
+ 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.
6
+ 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.
7
+
8
+ ## BFF Producer
9
+
10
+ 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.
11
+ When executing `dev` or `build`, the following artifacts for consumers will be automatically generated:
12
+ - API functions under the `dist/client` directory
13
+ - Runtime configuration functions under the `dist/runtime` directory
14
+ - Interface exports defined in `exports` field of `package.json`
15
+ - File list for npm publication specified in `files` field of `package.json`
16
+
17
+ ### Existing BFF-enabled Projects
18
+
19
+ 1. Enable Cross-Project Invocation
20
+
21
+ Ensure the current project has BFF enabled with API files defined under `api/lambda`. Add the following configuration:
22
+
23
+ ```ts title="modern.config.ts"
24
+ export default defineConfig({
25
+ bff: {
26
+ crossProject: true,
27
+ }
28
+ });
29
+ ```
30
+
31
+ 2. Generate SDK Type Files
32
+
33
+ To provide type hints for the integrated invocation SDK, enable the `declaration` option in TypeScript configuration:
34
+
35
+ ```ts title="tsconfig.json"
36
+ "compilerOptions": {
37
+ "declaration": true,
38
+ }
39
+ ```
40
+
41
+ ### Create BFF Application
42
+
43
+ import CreateApi from "@site-docs-en/components/create-bff-api-app"
44
+
45
+ <CreateApi/>
46
+
47
+ ## BFF Consumer
48
+
49
+ :::info
50
+ You can initiate requests to BFF producers from projects using any framework via the SDK.
51
+ :::
52
+
53
+ ### Intra-Monorepo Invocation
54
+
55
+ When producer and consumer are in the same Monorepo, directly import the SDK. API functions reside under `${package_name}/api`:
56
+
57
+ ```ts title="src/routes/page.tsx"
58
+ import { useState, useEffect } from 'react';
59
+ import { get as hello } from '${package_name}/api/hello';
60
+
61
+ export default () => {
62
+ const [text, setText] = useState('');
63
+
64
+ useEffect(() => {
65
+ hello().then(setText);
66
+ }, []);
67
+ return <div>{text}</div>;
68
+ };
69
+ ```
70
+
71
+ ### Cross-Project Invocation
72
+
73
+ 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.
74
+
75
+ ### Domain Configuration and Extensions
76
+
77
+ For real-world scenarios requiring custom BFF service domains, use the configuration function:
78
+
79
+ ```ts title="src/routes/page.tsx"
80
+ import { configure } from '${package_name}/runtime';
81
+
82
+ configure({
83
+ setDomain() {
84
+ return 'https://your-bff-api.com';
85
+ },
86
+ });
87
+ ```
88
+
89
+ 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:
90
+
91
+ ```ts title="src/routes/page.tsx"
92
+ import { configure } from '${package_name}/runtime';
93
+ import { configure as innerConfigure } from '@modern-js/runtime/bff';
94
+ import axios from 'axios';
95
+
96
+ configure({
97
+ setDomain() {
98
+ return 'https://your-bff-api.com';
99
+ },
100
+ });
101
+
102
+ innerConfigure({
103
+ async request(...config: Parameters<typeof fetch>) {
104
+ const [url, params] = config;
105
+ const res = await axios({
106
+ url: url as string,
107
+ method: params?.method as Method,
108
+ data: params?.body,
109
+ headers: {
110
+ 'x-header': 'innerConfigure',
111
+ },
112
+ });
113
+ return res.data;
114
+ },
115
+ });
116
+ ```
@@ -0,0 +1,25 @@
1
+
2
+ 1. 执行 `@modern-js/create` 命令:
3
+
4
+ ```bash
5
+ npx @modern-js/create@latest myapi
6
+ ```
7
+
8
+ 2. 可交互的问答界面中,按照默认的选择进行初始化:
9
+
10
+ ```bash
11
+ ? 请选择开发语言 TS
12
+ ? 请选择包管理工具 pnpm
13
+ ```
14
+
15
+ 3. 执行 `new` 命令,启用 BFF:
16
+
17
+ ```bash
18
+ ? 请选择你想要的操作 启用可选功能
19
+ ? 请选择功能名称 启用「BFF」功能
20
+ ? 请选择 BFF 类型 框架模式
21
+ ```
22
+
23
+
24
+ 4. 执行【[已启用 BFF 的项目](/guides/advanced-features/bff/cross-project.html#已启用-bff-的项目)】步骤,即可打开跨项目调用开关。
25
+ 需要注意的是,当项目仅作为 BFF 生产端,其运行时不依赖 `/src` 源码目录。因此,移除 `/src` 目录可在一定程度上优化工程的编译效率。
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  title: buildCache
3
+ configName: performance.buildCache
3
4
  ---
4
5
 
5
6
  # performance.buildCache
@@ -10,44 +11,25 @@ title: buildCache
10
11
  type BuildCacheConfig =
11
12
  | {
12
13
  /**
13
- * webpack 文件缓存系统的缓存目录
14
+ * 用于设置缓存文件的输出目录
14
15
  */
15
16
  cacheDirectory?: string;
16
17
  /**
17
18
  * 根据 cacheDigest 内容设置不同的缓存名称
18
19
  */
19
20
  cacheDigest?: Array<string | undefined>;
21
+ /**
22
+ * 一个包含构建依赖的文件数组。
23
+ * Rspack / webpack 将使用其中每个文件的哈希值来判断持久化缓存是否失效。
24
+ */
25
+ buildDependencies?: string[];
20
26
  }
21
27
  | boolean;
22
28
  ```
23
29
 
24
- - **默认值:**
25
-
26
- ```js
27
- const defaultBuildCacheConfig = {
28
- cacheDirectory: './node_modules/.cache/webpack',
29
- };
30
- ```
31
-
32
- - **打包工具:** `仅支持 webpack`
33
-
34
30
  控制 Modern.js 在构建过程中的缓存行为。
35
31
 
36
- Modern.js 默认会开启构建缓存来提升二次构建的速度,并默认把生成的缓存文件写到 `./node_modules/.cache/webpack` 目录下。
37
-
38
- 你可以通过 `buildCache` 配置缓存路径,比如:
39
-
40
- ```js
41
- export default {
42
- performance: {
43
- buildCache: {
44
- cacheDirectory: './node_modules/.custom_cache/webpack',
45
- },
46
- },
47
- };
48
- ```
49
-
50
- 如果不希望缓存,你也可以将 `buildCache` 置为 `false` 将其禁用掉:
32
+ 在使用 webpack 构建时,Modern.js 默认会开启构建缓存来提升二次构建的速度。如果不希望缓存,你可以将 `buildCache` 置为 `false` 将其禁用掉:
51
33
 
52
34
  ```js
53
35
  export default {
@@ -57,28 +39,8 @@ export default {
57
39
  };
58
40
  ```
59
41
 
60
- ### cacheDigest
42
+ 需要注意的是,Rspack 的持久化缓存处于[实验性阶段](https://rspack.dev/zh/config/experiments#experimentscache),可能会在未来的版本中发生变化,该功能需要手动开启。
61
43
 
62
- `cacheDigest` 用来添加一些会对构建结果产生影响的环境变量。Modern.js 将根据 `cacheDigest` 内容和当前构建模式来设置缓存名称,来确保不同的 `cacheDigest` 可以命中不同的缓存。
44
+ import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
63
45
 
64
- #### 示例
65
-
66
- 当前项目需要根据不同的 `APP_ID` 来设置不同的 extensions。默认情况下,由于当前项目的代码 & 配置 & 依赖未发生变化,会命中之前的缓存。
67
- 通过将 `APP_ID` 添加到 `cacheDigest` 中,在 `APP_ID` 变化时会去查找不同的缓存结果,从而避免命中不符合预期的缓存结果。
68
-
69
- ```js
70
- export default {
71
- tools: {
72
- bundlerChain: chain => {
73
- if (process.env.APP_ID === 'xxx') {
74
- chain.resolve.extensions.prepend('.ttp.ts');
75
- }
76
- },
77
- },
78
- performance: {
79
- buildCache: {
80
- cacheDigest: [process.env.APP_ID],
81
- },
82
- },
83
- };
84
- ```
46
+ <RsbuildConig />
@@ -1 +1 @@
1
- ["function", "frameworks", "extend-server", "sdk", "upload"]
1
+ ["function", "frameworks", "extend-server", "sdk", "upload", "cross-project"]
@@ -0,0 +1,120 @@
1
+ import { PackageManagerTabs } from '@theme';
2
+
3
+ # 跨项目调用
4
+
5
+ 基于 BFF 架构,Modern.js 提供了跨项目调用的能力,即在一个项目中创建的 BFF 函数可以被其他项目进行一体化调用,实现项目间的函数共享和功能复用。
6
+ 跨项目调用分为 BFF 的**生产端**和**消费端**。生产端负责创建和提供 BFF 服务、生成一体化调用 SDK,而消费端通过调用 SDK 发起接口请求。
7
+
8
+ ## BFF 生产端
9
+
10
+ 升级 Modern.js 相关依赖到 x.64.4 及以上版本,通过配置即可启用跨项目调用能力。你可以将已启用 BFF 能力的项目视为 BFF 生产端,也可以单独创建独立的 BFF 应用。
11
+ 当执行 `dev` 或 `build`,都会自动生成供消费端使用的产物,包括:
12
+ - `dist/client` 目录下的接口函数
13
+ - `dist/runtime` 目录下的运行时配置函数
14
+ - `package.json` 中 `exports` 定义接口函数出口
15
+ - `package.json` 中 `files` 指定发布到 npm 包的文件列表
16
+
17
+ ### 已启用 BFF 的项目
18
+
19
+ 1. 开启跨项目调用
20
+
21
+ 确保当前项目已启动 BFF 能力,并在 `api/lambda` 目录下定义接口文件。完成如下配置:
22
+
23
+ ```ts title="modern.config.ts"
24
+ export default defineConfig({
25
+ bff: {
26
+ crossProject: true,
27
+ }
28
+ });
29
+ ```
30
+
31
+
32
+ 2. 生成 SDK 类型文件
33
+
34
+ 为一体化调用 SDK 提供类型提示,需要在 `TypeScript` 的 `tsconfig.json` 文件中打开 `declaration` 选项,配置如下:
35
+
36
+ ```ts title="tsconfig.json"
37
+ "compilerOptions": {
38
+ "declaration": true,
39
+ }
40
+ ```
41
+
42
+ ### 创建 BFF 应用
43
+
44
+ import CreateApi from "@site-docs/components/create-bff-api-app"
45
+
46
+ <CreateApi/>
47
+
48
+ ## BFF 消费端
49
+
50
+ :::info
51
+ 你可以在任意框架的项目中通过调用 SDK 向 BFF 生产端发起接口请求。
52
+ :::
53
+
54
+ ### 同一 Monorepo 内调用
55
+
56
+ 如果生产端和消费端在同一 Monorepo 中,可以直接引入 SDK。接口函数位于 `${package_name}/api` 目录下,示例如下:
57
+
58
+ ```ts title="src/routes/page.tsx"
59
+ import { useState, useEffect } from 'react';
60
+ import { get as hello } from '${package_name}/api/hello';
61
+
62
+ export default () => {
63
+ const [text, setText] = useState('');
64
+
65
+ useEffect(() => {
66
+ hello().then(setText);
67
+ }, []);
68
+ return <div>{text}</div>;
69
+ };
70
+ ```
71
+
72
+ ### 独立项目间调用
73
+
74
+ 当生产端和消费端不在同一个 Monorepo 中时,生产端需要通过 `npm publish` 将 BFF 生产端项目发布为包,调用方式与 Monorepo 内相同。
75
+
76
+ ### 配置域名及扩展功能
77
+
78
+ 实际应用场景中,跨项目调用需要指定 BFF 服务的域名。可以通过以下配置函数实现:
79
+
80
+ ```ts title="src/routes/page.tsx"
81
+ import { configure } from '${package_name}/runtime';
82
+
83
+ configure({
84
+ setDomain() {
85
+ return 'https://your-bff-api.com';
86
+ },
87
+ });
88
+ ```
89
+
90
+ `${package_name}/runtime` 目录下的 `configure` 函数,支持通过 `setDomain` 配置域名,`configure` 同样支持添加拦截器和自定义请求 SDK 能力。
91
+ 当需要在同一页面中同时对**当前项目**和**跨项目**的一体化调用 SDK 进行扩展,建议采用以下配置:
92
+
93
+ ```ts title="src/routes/page.tsx"
94
+ import { configure } from '${package_name}/runtime';
95
+ import { configure as innerConfigure } from '@modern-js/runtime/bff';
96
+ import axios from 'axios';
97
+
98
+ configure({
99
+ setDomain() {
100
+ return 'https://your-bff-api.com';
101
+ },
102
+ });
103
+
104
+ innerConfigure({
105
+ async request(...config: Parameters<typeof fetch>) {
106
+ const [url, params] = config;
107
+ const res = await axios({
108
+ url: url as string,
109
+ method: params?.method as Method,
110
+ data: params?.body,
111
+ headers: {
112
+ 'x-header': 'innerConfigure',
113
+ },
114
+ });
115
+ return res.data;
116
+ },
117
+ });
118
+
119
+
120
+ ```
package/package.json CHANGED
@@ -15,14 +15,14 @@
15
15
  "modern",
16
16
  "modern.js"
17
17
  ],
18
- "version": "2.64.2",
18
+ "version": "2.65.0",
19
19
  "publishConfig": {
20
20
  "registry": "https://registry.npmjs.org/",
21
21
  "access": "public",
22
22
  "provenance": true
23
23
  },
24
24
  "dependencies": {
25
- "@modern-js/sandpack-react": "2.64.2"
25
+ "@modern-js/sandpack-react": "2.65.0"
26
26
  },
27
27
  "devDependencies": {
28
28
  "@rspress/shared": "1.40.2",