@bleedingdev/modern-js-main-doc 3.4.0-ultramodern.9 → 3.5.0-ultramodern.1
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.
- package/docs/en/community/blog/v3-release-note.mdx +1 -1
- package/docs/en/configure/app/bff/effect.mdx +116 -3
- package/docs/en/configure/app/bff/runtime-framework.mdx +4 -2
- package/docs/en/configure/app/experiments/source-build.mdx +1 -1
- package/docs/en/configure/app/html/template-parameters.mdx +1 -1
- package/docs/en/configure/app/output/convert-to-rem.mdx +1 -1
- package/docs/en/configure/app/security/check-syntax.mdx +1 -1
- package/docs/en/configure/app/tools/html-plugin.mdx +1 -1
- package/docs/en/configure/app/tools/ts-checker.mdx +20 -1
- package/docs/en/guides/advanced-features/bff/data-platform.mdx +4 -4
- package/docs/en/guides/advanced-features/bff/frameworks.mdx +25 -14
- package/docs/en/guides/advanced-features/bff/function.mdx +4 -0
- package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx +1 -1
- package/docs/en/guides/basic-features/debug/using-storybook.mdx +1 -1
- package/docs/en/guides/basic-features/static-assets/json-files.mdx +2 -2
- package/docs/en/guides/get-started/_meta.json +2 -1
- package/docs/en/guides/get-started/ai-coding-agents.mdx +48 -0
- package/docs/en/guides/get-started/ultramodern.mdx +113 -23
- package/docs/en/guides/upgrade/config.mdx +1 -1
- package/docs/en/plugin/introduction.mdx +9 -9
- package/docs/zh/community/blog/v3-release-note.mdx +1 -1
- package/docs/zh/configure/app/bff/effect.mdx +109 -3
- package/docs/zh/configure/app/bff/runtime-framework.mdx +4 -2
- package/docs/zh/configure/app/experiments/source-build.mdx +1 -1
- package/docs/zh/configure/app/html/template-parameters.mdx +1 -1
- package/docs/zh/configure/app/output/convert-to-rem.mdx +1 -1
- package/docs/zh/configure/app/security/check-syntax.mdx +1 -1
- package/docs/zh/configure/app/tools/html-plugin.mdx +1 -1
- package/docs/zh/configure/app/tools/ts-checker.mdx +19 -0
- package/docs/zh/guides/advanced-features/bff/data-platform.mdx +2 -2
- package/docs/zh/guides/advanced-features/bff/frameworks.mdx +24 -14
- package/docs/zh/guides/advanced-features/page-performance/optimize-bundle.mdx +1 -1
- package/docs/zh/guides/basic-features/debug/using-storybook.mdx +1 -1
- package/docs/zh/guides/basic-features/static-assets/json-files.mdx +2 -2
- package/docs/zh/guides/get-started/_meta.json +2 -1
- package/docs/zh/guides/get-started/ai-coding-agents.mdx +48 -0
- package/docs/zh/guides/get-started/ultramodern.mdx +92 -19
- package/docs/zh/guides/upgrade/config.mdx +1 -1
- package/docs/zh/plugin/introduction.mdx +9 -9
- package/package.json +2 -2
|
@@ -89,4 +89,4 @@ pnpm storybook
|
|
|
89
89
|
|
|
90
90
|
## 示例
|
|
91
91
|
|
|
92
|
-
你可以查看 [示例](https://github.com/
|
|
92
|
+
你可以查看 [示例](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。
|
|
@@ -38,7 +38,7 @@ import { name } from './example.json';
|
|
|
38
38
|
|
|
39
39
|
YAML 是一种数据序列化语言,通常用于编写配置文件。
|
|
40
40
|
|
|
41
|
-
你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/
|
|
41
|
+
你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml) 来支持引用 `.yaml` 或 `.yml` 文件,它们会被自动转换为 JSON 格式。
|
|
42
42
|
|
|
43
43
|
```ts
|
|
44
44
|
import { defineConfig } from '@modern-js/app-tools';
|
|
@@ -85,7 +85,7 @@ declare module '*.yml' {
|
|
|
85
85
|
|
|
86
86
|
TOML 是一种语义明显、易于阅读的配置文件格式。
|
|
87
87
|
|
|
88
|
-
你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/
|
|
88
|
+
你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml) 来支持引用 `.toml` 文件,它会被自动转换为 JSON 格式。
|
|
89
89
|
|
|
90
90
|
```ts
|
|
91
91
|
import { defineConfig } from '@modern-js/app-tools';
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: AI 工具
|
|
3
|
+
sidebar_position: 6
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Modern.js For AI
|
|
7
|
+
|
|
8
|
+
Modern.js 为 AI Agent 提供了一套工具套件,帮助开发者利用 AI 高效完成 Modern.js 应用的功能开发、依赖升级与版本迁移工作。
|
|
9
|
+
|
|
10
|
+
## llms.txt
|
|
11
|
+
|
|
12
|
+
Modern.js 文档遵循 [llms.txt 规范](https://llmstxt.org/),由 [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) 自动生成,可通过 `/llms.txt` 或 `/llms-full.txt` 供 AI 工具检索:
|
|
13
|
+
|
|
14
|
+
- 索引:[`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
|
|
15
|
+
- 全文:`https://modernjs.dev/llms-full.txt`(体积较大,按需取片段)
|
|
16
|
+
|
|
17
|
+
大部分「这个 API / 配置是什么」类问题,靠 llms.txt 即可解决。让你的 Agent 按需检索它即可,不必把文档复制进项目。
|
|
18
|
+
|
|
19
|
+
## Skills
|
|
20
|
+
|
|
21
|
+
Skills 是按需触发的 AI 辅助能力,遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。用户向 Skills:
|
|
22
|
+
|
|
23
|
+
| Skill | 标识 | 说明 |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| 升级到 v3 | `modernjs-migrate-to-v3` | v2 应用迁移到 v3:安全改写 + 复杂项人工清单 + 迁移报告 |
|
|
26
|
+
| 启用特性 | `modernjs-feature-enable` | 为 v3 应用启用 BFF / SSG / styled-components,并脚手架化 Tailwind CSS / 自定义 Web Server |
|
|
27
|
+
|
|
28
|
+
> Skills 默认不强装、不隐式安装,由你显式安装。RSC、微前端等属于配置或架构决策,不是 `modernjs-feature-enable` 的一键启用项。
|
|
29
|
+
|
|
30
|
+
## 安装 Skills
|
|
31
|
+
|
|
32
|
+
Modern.js 的用户向 Skill 就放在仓库根 `skills/` 目录,遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。推荐用标准的 `skills` CLI 直接从 GitHub 安装:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# 列出可安装的 Skills
|
|
36
|
+
npx skills add web-infra-dev/modern.js --list
|
|
37
|
+
|
|
38
|
+
# 安装单个 Skill 到你的 Agent 目录(--agent 可选 claude-code / codex / cursor 等)
|
|
39
|
+
npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
它会把整个 Skill 目录(`SKILL.md` + `scripts/` + `references/`)安装到对应 Agent 目录,随后即可在该 Agent 里触发。
|
|
43
|
+
|
|
44
|
+
> 需锁定到某个版本时,在仓库后加 `#<ref>`(ref 可为 tag / 分支 / commit),即安装该版本上的 Skill(把 `<tag>` 换成含本 Skill 的发布 tag):
|
|
45
|
+
>
|
|
46
|
+
> ```bash
|
|
47
|
+
> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
|
|
48
|
+
> ```
|
|
@@ -7,14 +7,14 @@ sidebar_position: 2
|
|
|
7
7
|
|
|
8
8
|
本文对比 **UltraModern.js 3.0** 与本 fork 持续跟进的 Modern.js 3.x 版本线。这里的基线应理解为当前已合并的 Modern.js `release-v3.x` 基线,而不是固定的补丁版本快照。
|
|
9
9
|
|
|
10
|
-
UltraModern.js 3.0 是我们从 Modern.js 分叉出来的 SuperApp 框架。它保留有利于接入的 Modern.js 插件/运行时心智模型,但产品定位是独立框架:面向 Effect-first
|
|
10
|
+
UltraModern.js 3.0 是我们从 Modern.js 分叉出来的 SuperApp 框架。它保留有利于接入的 Modern.js 插件/运行时心智模型,但产品定位是独立框架:面向 Effect HttpApi-first HTTP API、TanStack Router、SSR、Module Federation 与可独立部署的 Micro Verticals。
|
|
11
11
|
|
|
12
12
|
## 设计原则
|
|
13
13
|
|
|
14
14
|
- 差异要明确、可审计。
|
|
15
|
-
-
|
|
15
|
+
- 明确维护与上游 Modern.js 的合并兼容性:通用 Modern.js 运行时代码保留在其应在的位置,UltraModern 生成 surface 保持严格。
|
|
16
16
|
- 仅在跨团队稳定性场景增加平台契约。
|
|
17
|
-
-
|
|
17
|
+
- 保留显式 escape hatch,但它们必须位于生成 HTTP API 模块之外。
|
|
18
18
|
|
|
19
19
|
## 兼容性承诺
|
|
20
20
|
|
|
@@ -24,7 +24,7 @@ UltraModern.js 3.0 保持以下不变:
|
|
|
24
24
|
- 既有项目结构与命令使用方式。
|
|
25
25
|
- 渐进式接入路径(应用无需大规模重构)。
|
|
26
26
|
|
|
27
|
-
UltraModern.js 的增强能力是新 SuperApp
|
|
27
|
+
UltraModern.js 的增强能力是新 SuperApp 的默认产品面。框架方向是 Effect + TanStack + SSR + Micro Verticals,生成的 HTTP API 只走严格 Effect HttpApi surface。既有 Modern.js 应用可以渐进迁移;一旦某个 API surface 被生成为或迁移为 UltraModern HTTP API,就必须使用严格 Effect HttpApi 路径。
|
|
28
28
|
|
|
29
29
|
## 有意引入的差异(3.0 线)
|
|
30
30
|
|
|
@@ -33,7 +33,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
|
|
|
33
33
|
| 构建诊断能力 | RsDoctor 多为显式开启 | 新增一等的 `performance.rsdoctor` 配置项(按需开启;早期的默认开启行为与诊断契约产物已回退) |
|
|
34
34
|
| 输出与静态资源回源 | 预压缩策略通常由业务自定义 | 默认开启 `output.precompress`,并按 `Accept-Encoding` 协商 `.br` / `.gz` 回源 |
|
|
35
35
|
| BFF 运行时与契约 | 提供标准 BFF 运行时与客户端生成能力 | 增加 `requestId` 维度隔离、初始化 fail-fast 校验与操作/追踪关联 Header |
|
|
36
|
-
| BFF 运行时选型 |
|
|
36
|
+
| BFF 运行时选型 | 标准 request-handler BFF 路径 | 生成的 HTTP API 只走 Effect `HttpApi`,入口固定为 `api/index.ts`,共享契约固定为 `shared/api.ts`,并通过 `strictEffectApproach`、Oxlint 与生成检查拒绝原始 request handler、手写解析、手写 `Response` 和 Hono server import |
|
|
37
37
|
| Telemetry 标准化 | 可观测链路通常由业务侧自行拼装 | 增加框架级 telemetry 管线,内置 OTLP/VictoriaMetrics,支持脱敏、批处理与背压 |
|
|
38
38
|
| 应用级 MF SSR 协议 | 没有以 super-app 为重点的应用级稳定性契约开关 | 增加 `server.ssr.moduleFederationAppSSR` 配置/环境变量握手,并补齐集成级回归保障 |
|
|
39
39
|
| MF vertical 加载可靠性 | 重试/降级策略通常由各业务单独实现 | 增加 timeout/network/contract-error 的确定性可靠性矩阵与分布式 OTEL 连续性断言 |
|
|
@@ -46,16 +46,17 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
|
|
|
46
46
|
|
|
47
47
|
- 不再把这个 fork 隐藏在旧 Modern.js 品牌后面。
|
|
48
48
|
- 当通用 Modern.js 默认值与 SuperApp 可靠性冲突时,不优先优化通用默认值。
|
|
49
|
-
-
|
|
49
|
+
- 不为了执行 UltraModern 策略而删除通用 Modern.js 的 Hono/file-convention 运行时支持;约束应落在 UltraModern 生成器、配置、检查和生成 workspace 中。
|
|
50
|
+
- 生成的 UltraModern HTTP API 只走严格 Effect HttpApi surface;原始 request handler 和 Hono/file-function API 不属于生成架构。
|
|
50
51
|
- 除非稳定性硬需求,否则避免引入破坏性 API 变更。
|
|
51
52
|
|
|
52
53
|
## 迁移指南
|
|
53
54
|
|
|
54
|
-
对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold
|
|
55
|
+
对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队,迁移路径是把 API 工作迁到严格 Effect HttpApi surface,而不是保留旧的原始 handler 布局。
|
|
55
56
|
|
|
56
|
-
1. 既有
|
|
57
|
-
2. 新建或迁移中的 BFF
|
|
58
|
-
3.
|
|
57
|
+
1. 既有 Modern.js 应用在尚未进入生成 UltraModern surface 前可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径,团队可以按自己的节奏迁移路由层。
|
|
58
|
+
2. 新建或迁移中的 BFF 能力使用 `bff.runtimeFramework: 'effect'`、`bff.effect.entry: './api/index'` 和 `bff.effect.strictEffectApproach: true`。接口先改 `shared/api.ts` 的 `HttpApi` 契约,再在 `api/index.ts` 用 `defineEffectBff(...)` / `HttpApiBuilder` 实现。
|
|
59
|
+
3. 在生成或已迁移的 UltraModern workspace 中,把 raw handler、`api/lambda/**`、手写 `Response` 和手写 request parsing 视为迁移缺陷。
|
|
59
60
|
4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成 workspace 会自带 `.github/workflows/ultramodern-workspace-gates.yml`,因此 `pnpm check` 与 `pnpm build` 从第一天开始就是本地接入契约的一部分;CI 会以并行矩阵运行这些基础 gate。
|
|
60
61
|
|
|
61
62
|
旧版生成 workspace 迁移时,以已发布的包 cohort 作为事实来源:
|
|
@@ -70,9 +71,76 @@ mise exec -- pnpm check
|
|
|
70
71
|
mise exec -- pnpm build
|
|
71
72
|
```
|
|
72
73
|
|
|
74
|
+
严格生成 API 迁移要求 `3.5.0-ultramodern.1` 或更新版本。
|
|
75
|
+
`3.4.0-ultramodern.20` 及更早 cohort 还没有这套完整的直接
|
|
76
|
+
`api/index.ts` 生成器、生成的 `.mts` 检查、严格 Oxlint 边界规则、Effect 版本组
|
|
77
|
+
overrides 和严格 Effect 迁移命令。还不能安装该 BleedingDev cohort 的 agent 应使用本地
|
|
78
|
+
Modern.js workspace 做迁移校验;否则用 `--ultramodern-package-version` 固定
|
|
79
|
+
`3.5.0-ultramodern.1` 或更新版本。
|
|
80
|
+
|
|
81
|
+
手写 package alias 或生成 metadata 之前,先在目标 workspace 运行框架迁移命令:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.1 ultramodern \
|
|
85
|
+
migrate-strict-effect --version 3.5.0-ultramodern.1
|
|
86
|
+
pnpm api:check
|
|
87
|
+
pnpm contract:check
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
该命令会更新 `.modernjs/ultramodern.json`、根 `modernjs.packageSource`、生成的
|
|
91
|
+
Modern package alias、直接 topology API metadata 和 pnpm lockfile。剩余失败就是源码迁移:
|
|
92
|
+
把代码移到 `shared/api.ts`、`api/index.ts` 和 `src/api/*-client.ts`,再删除
|
|
93
|
+
`api/effect`、`api/lambda`、`shared/effect` 和 `src/effect`。
|
|
94
|
+
|
|
95
|
+
严格 Effect 生成 workspace 会通过 pnpm overrides 固定兼容版本组:
|
|
96
|
+
`effect@4.0.0-beta.89` 和 `@effect/vitest@4.0.0-beta.89`。不要添加与这些
|
|
97
|
+
overrides 冲突的 app 本地直接 Effect 版本。
|
|
98
|
+
|
|
99
|
+
渐进迁移意味着尚未迁移的旧 Modern.js app 可以保留现有 runtime,直到被转换为
|
|
100
|
+
UltraModern。一个 surface 一旦生成为或迁移为 UltraModern HTTP API,就只能使用
|
|
101
|
+
Effect HttpApi;不要在该 UltraModern API surface 中保留 Hono、lambda handler 或原始
|
|
102
|
+
request handler。
|
|
103
|
+
|
|
104
|
+
迁移已经带有 Effect API 文件的生成 workspace 时,明确移动文件,不保留兼容别名:
|
|
105
|
+
|
|
106
|
+
1. 将每个 vertical 服务端入口从 `verticals/<id>/api/effect/index.ts` 移到
|
|
107
|
+
`verticals/<id>/api/index.ts`。
|
|
108
|
+
2. 将每个共享 API 契约从 `verticals/<id>/shared/effect/api.ts` 移到
|
|
109
|
+
`verticals/<id>/shared/api.ts`。
|
|
110
|
+
3. 将生成客户端从 `verticals/<id>/src/effect/*-client.ts` 移到
|
|
111
|
+
`verticals/<id>/src/api/*-client.ts`。
|
|
112
|
+
4. 将 shell API 聚合从 `apps/shell-super-app/src/effect/*` 移到
|
|
113
|
+
`apps/shell-super-app/src/api/*`。
|
|
114
|
+
5. 更新 imports 和 package exports,使用 `./api`、`./api/client` 与
|
|
115
|
+
`@<workspace>/<vertical>/api/client`;删除 `./effect/client`、
|
|
116
|
+
`./shared/effect/api` 和 shared Effect API 包。
|
|
117
|
+
6. 更新每个 vertical 的 `modern.config.ts`,设置
|
|
118
|
+
`bff.effect.entry: './api/index'` 和
|
|
119
|
+
`bff.effect.strictEffectApproach: true`。
|
|
120
|
+
7. 更新 topology,让 API metadata 直接位于 `api` 下,并设置
|
|
121
|
+
`api.bff.strictEffectApproach: true`;不要保留 `api.effect`。
|
|
122
|
+
8. 运行 `pnpm api:check`、`scripts/validate-ultramodern-workspace.mts`、
|
|
123
|
+
`pnpm check` 和 `pnpm build`。
|
|
124
|
+
|
|
125
|
+
如果迁移失败,应修复归属的生成契约、topology、package exports 或 API 模块。
|
|
126
|
+
不要添加 app 级 alias、原始 request handler、手写 `Response`、本地类型断言或包
|
|
127
|
+
shim 来让旧布局通过。
|
|
128
|
+
|
|
129
|
+
Effect RPC、WebSockets 和其他传输方式应在需要时作为显式 transport surface 增加。
|
|
130
|
+
它们不能作为在生成 HTTP API 模块中重新引入原始 request handler 的理由。
|
|
131
|
+
|
|
132
|
+
严格 API 测试应执行 `HttpApi` 契约。Edge 兼容 proof 测试使用
|
|
133
|
+
`@modern-js/plugin-bff/effect-edge` 的 `createEffectBffTestHandler`;如果必须手动组合
|
|
134
|
+
web handler,在调用 `HttpRouter.toWebHandler` 前要把 `HttpServer.layerServices` 和
|
|
135
|
+
API group layer 一起提供。
|
|
136
|
+
|
|
137
|
+
动态 origin CORS predicate 使用
|
|
138
|
+
`HttpRouter.middleware(Effect.succeed(HttpMiddleware.cors(...)))`。在固定的 Effect
|
|
139
|
+
版本组中,`HttpRouter.middleware(...)` 直接返回 `Layer`;不要读取 `.layer` 属性。
|
|
140
|
+
|
|
73
141
|
每个仓库只使用一种 package-source 策略。已发布的 BleedingDev create 包默认使用
|
|
74
142
|
`--ultramodern-package-source=install`,并把精确 cohort 记录到
|
|
75
|
-
`.modernjs/ultramodern
|
|
143
|
+
`.modernjs/ultramodern.json`。`--workspace` 只用于本地 monorepo
|
|
76
144
|
联调未发布包。发布证明和 CI 如果需要证明某个已发布框架版本,应使用
|
|
77
145
|
`--ultramodern-package-version` 固定精确 cohort。
|
|
78
146
|
|
|
@@ -82,16 +150,21 @@ Federation shim 或自定义 server wrapper。框架 BFF compiler 会把服务
|
|
|
82
150
|
CommonJS,同时生成的 app package 继续为 Module Federation DTS 保留稳定的
|
|
83
151
|
`typescript`,并使用固定的 `@typescript/native-preview` 工具链执行 TS-Go 检查。
|
|
84
152
|
|
|
85
|
-
安装新 cohort 后,先运行生成的
|
|
86
|
-
`scripts/validate-ultramodern-workspace.
|
|
153
|
+
安装新 cohort 后,先运行生成的 `pnpm api:check` 与
|
|
154
|
+
`scripts/validate-ultramodern-workspace.mts` 契约校验,再接受人工改动。topology、
|
|
87
155
|
ownership、package-source、本地 overlay、生成契约、Tailwind prefix 或 Module
|
|
88
156
|
Federation 冲突,都应在对应归属文件中修复,不要手写补丁覆盖生成结果。
|
|
89
157
|
|
|
158
|
+
Cloudflare D1 绑定使用一等配置 `deploy.worker.d1Databases`;生成 app 拥有 D1
|
|
159
|
+
migration 时不要再用 app 本地 postprocess。Cloudflare public output 默认排除服务端
|
|
160
|
+
`api` 和 `shared` 目录,并且生成的 Modern/Rspack cache 会按 app 与构建目标隔离,避免
|
|
161
|
+
本地 `build` 与 `cloudflare:build` 共享同一个 Rspack cache 目录。
|
|
162
|
+
|
|
90
163
|
## 人类工作流
|
|
91
164
|
|
|
92
165
|
公开的 BleedingDev create 包只有一个受支持的生成产品。默认命令会创建一个
|
|
93
166
|
可上线的 UltraModern SuperApp workspace,包含 `presetUltramodern(...)`、
|
|
94
|
-
SSR、TanStack Router、Tailwind CSS v4、i18n、Effect BFF、Module Federation
|
|
167
|
+
SSR、TanStack Router、Tailwind CSS v4、i18n、Effect HttpApi BFF、Module Federation
|
|
95
168
|
topology、生成质量 gate,以及 Cloudflare 部署基础:
|
|
96
169
|
|
|
97
170
|
```bash
|
|
@@ -115,7 +188,7 @@ mise exec -- pnpm check
|
|
|
115
188
|
|
|
116
189
|
`--vertical` 会修改当前 workspace:创建 vertical 包,并更新 topology 元数据、
|
|
117
190
|
ownership 记录、shell Module Federation、开发 overlays、包依赖、生成契约、
|
|
118
|
-
端口、路由归属 i18n、CSS 隔离,以及 vertical 自己拥有的 Effect
|
|
191
|
+
端口、路由归属 i18n、CSS 隔离,以及 vertical 自己拥有的 Effect HttpApi/client surface。
|
|
119
192
|
|
|
120
193
|
### 生成器自动化
|
|
121
194
|
|
|
@@ -166,9 +239,9 @@ addUltramodernVertical({
|
|
|
166
239
|
```
|
|
167
240
|
|
|
168
241
|
公开结果包含 workspace root、包源、创建的 apps、创建路径、重写路径、分配端口、
|
|
169
|
-
Module Federation 名称、
|
|
242
|
+
Module Federation 名称、API 前缀、生成契约路径与 warnings。
|
|
170
243
|
MicroVertical dry-run 返回相同结构,并额外包含 `dryRun`、`selectedPort`、
|
|
171
|
-
`moduleFederationRemote`、`
|
|
244
|
+
`moduleFederationRemote`、`apiPrefix`、`jsonMutations`、
|
|
172
245
|
`shellDependencyChanges` 与 `generatedContractChanges`;CLI 会输出 JSON,且不写文件。
|
|
173
246
|
|
|
174
247
|
CodeSmith 消费方可以使用 adapter subpath:
|
|
@@ -215,7 +288,7 @@ JSON-LD 是可选的路由 metadata,不会自动推断。私有路由和不可
|
|
|
215
288
|
JSON-LD。公开路由 owner 可以在本地化路径旁显式添加 `jsonLd`,并使用生成的
|
|
216
289
|
`src/routes/ultramodern-jsonld.ts` helper 编写常见 schema.org 结构。
|
|
217
290
|
|
|
218
|
-
生成契约会在 `.modernjs/ultramodern
|
|
291
|
+
生成契约会在 `.modernjs/ultramodern.json` 中写入
|
|
219
292
|
`cssFederation`:
|
|
220
293
|
|
|
221
294
|
- `packages/shared-design-tokens` 拥有共享 token layer,并导出 `./tokens.css`。
|
|
@@ -224,7 +297,7 @@ JSON-LD。公开路由 owner 可以在本地化路径旁显式添加 `jsonLd`,
|
|
|
224
297
|
- Tailwind CSS v4 通过 `@tailwindcss/postcss` 保持在每个生成应用内部;共享 base style 不应由 vertical 重复定义。
|
|
225
298
|
- SSR 首屏依赖 Modern/Rspack 产出共享 token CSS 和应用自己的 CSS。Vertical CSS 通过 manifest 归属加载,不复制到 shell 源码中。
|
|
226
299
|
|
|
227
|
-
版本切换必须从同一个 vertical build marker 选择 UI、
|
|
300
|
+
版本切换必须从同一个 vertical build marker 选择 UI、API、CSS、i18n JSON 与 MF manifest 证据。只切换 shell 渲染里的 UI marker 不足以证明完整版本切换。
|
|
228
301
|
|
|
229
302
|
### 校验与部署
|
|
230
303
|
|
|
@@ -314,7 +314,7 @@ export default {
|
|
|
314
314
|
|
|
315
315
|
### tools.pug
|
|
316
316
|
|
|
317
|
-
**变更内容**:该配置已废弃,使用 Rsbuild 的 [Pug 插件](https://github.com/
|
|
317
|
+
**变更内容**:该配置已废弃,使用 Rsbuild 的 [Pug 插件](https://github.com/rstackjs/rsbuild-plugin-pug) 来启用支持。
|
|
318
318
|
|
|
319
319
|
**迁移示例**:
|
|
320
320
|
|
|
@@ -131,21 +131,21 @@ Rsbuild 是 Modern.js 底层的构建工具,通过添加 Rsbuild 插件可修
|
|
|
131
131
|
| [React 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-react) | 提供对 React 的支持 | - |
|
|
132
132
|
| [SVGR 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-svgr) | 支持将 SVG 图片转换为一个 React 组件 | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export) |
|
|
133
133
|
| [Assets Retry 插件](https://github.com/rstackjs/rsbuild-plugin-assets-retry) | 用于在静态资源加载失败时自动发起重试请求 | [output.assetsRetry](/configure/app/output/assets-retry.html) |
|
|
134
|
-
| [Type Check 插件](https://github.com/
|
|
135
|
-
| [Source Build 插件](https://github.com/
|
|
136
|
-
| [Check Syntax 插件](https://github.com/
|
|
137
|
-
| [CSS Minimizer 插件](https://github.com/
|
|
138
|
-
| [Rem 插件](https://github.com/
|
|
134
|
+
| [Type Check 插件](https://github.com/rstackjs/rsbuild-plugin-type-check) | 用于在单独的进程中运行 TypeScript 类型检查 | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
|
|
135
|
+
| [Source Build 插件](https://github.com/rstackjs/rsbuild-plugin-source-build) | 用于 monorepo 场景,支持引用其他子目录的源代码,并完成构建和热更新 | [experiments.sourceBuild](/configure/app/experiments/source-build.html) |
|
|
136
|
+
| [Check Syntax 插件](https://github.com/rstackjs/rsbuild-plugin-check-syntax) | 用于分析产物的语法兼容性,判断是否存在导致兼容性问题的高级语法 | [security.checkSyntax](/configure/app/security/check-syntax.html) |
|
|
137
|
+
| [CSS Minimizer 插件](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | 用于自定义 CSS 压缩工具,切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩 | [tools.minifyCss](/configure/app/tools/minify-css.html) |
|
|
138
|
+
| [Rem 插件](https://github.com/rstackjs/rsbuild-plugin-rem) | 用于实现移动端页面的 rem 自适应布局 | [output.convertToRem](/configure/app/output/convert-to-rem.html) |
|
|
139
139
|
|
|
140
140
|
#### 未内置的插件
|
|
141
141
|
|
|
142
142
|
以下是未在 Modern.js 中内置的 Rsbuild 官方插件:
|
|
143
143
|
|
|
144
|
-
- [Image Compress 插件](https://github.com/
|
|
144
|
+
- [Image Compress 插件](https://github.com/rstackjs/rsbuild-plugin-image-compress):将项目中用到的图片资源进行压缩处理。
|
|
145
145
|
- [Stylus 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-stylus):使用 Stylus 作为 CSS 预处理器。
|
|
146
|
-
- [UMD 插件](https://github.com/
|
|
147
|
-
- [YAML 插件](https://github.com/
|
|
148
|
-
- [TOML 插件](https://github.com/
|
|
146
|
+
- [UMD 插件](https://github.com/rstackjs/rsbuild-plugin-umd):用于构建 UMD 格式的产物。
|
|
147
|
+
- [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml):用于引用 YAML 文件,并将其转换为 JavaScript 对象。
|
|
148
|
+
- [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml):用于引用 TOML 文件,并将其转换为 JavaScript 对象。
|
|
149
149
|
|
|
150
150
|
import OtherPlugins from '@site-docs/components/other-plugins.mdx';
|
|
151
151
|
|
package/package.json
CHANGED
|
@@ -19,14 +19,14 @@
|
|
|
19
19
|
"modern.js",
|
|
20
20
|
"ultramodern.js"
|
|
21
21
|
],
|
|
22
|
-
"version": "3.
|
|
22
|
+
"version": "3.5.0-ultramodern.1",
|
|
23
23
|
"publishConfig": {
|
|
24
24
|
"registry": "https://registry.npmjs.org/",
|
|
25
25
|
"access": "public"
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
28
|
"mermaid": "^11.15.0",
|
|
29
|
-
"@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.
|
|
29
|
+
"@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.5.0-ultramodern.1"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
32
|
"@rsbuild/plugin-sass": "2.0.0",
|