@bleedingdev/modern-js-main-doc 3.9.0-ultramodern.9 → 3.9.3-ultramodern.2

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.
Files changed (32) hide show
  1. package/docs/en/components/deploy-command.mdx +1 -0
  2. package/docs/en/components/prerequisites.mdx +1 -1
  3. package/docs/en/configure/app/bff/effect.mdx +5 -12
  4. package/docs/en/configure/app/output/disable-svgr.mdx +4 -0
  5. package/docs/en/configure/app/output/svg-default-export.mdx +4 -0
  6. package/docs/en/configure/app/source/react-compiler.mdx +2 -0
  7. package/docs/en/configure/app/tools/less.mdx +95 -19
  8. package/docs/en/configure/app/tools/sass.mdx +88 -18
  9. package/docs/en/configure/app/tools/svgr.mdx +93 -0
  10. package/docs/en/configure/app/tools/ts-checker.mdx +3 -17
  11. package/docs/en/guides/basic-features/render/ssr-cache.mdx +14 -1
  12. package/docs/en/guides/basic-features/static-assets/svg-assets.mdx +29 -17
  13. package/docs/en/guides/get-started/ultramodern.mdx +45 -14
  14. package/docs/en/plugin/introduction.mdx +1 -1
  15. package/docs/en/plugin/server-plugins/api.mdx +1 -0
  16. package/docs/zh/components/deploy-command.mdx +1 -0
  17. package/docs/zh/components/prerequisites.mdx +1 -1
  18. package/docs/zh/configure/app/bff/effect.mdx +4 -11
  19. package/docs/zh/configure/app/output/disable-svgr.mdx +4 -0
  20. package/docs/zh/configure/app/output/svg-default-export.mdx +4 -0
  21. package/docs/zh/configure/app/source/react-compiler.mdx +2 -0
  22. package/docs/zh/configure/app/tools/less.mdx +94 -19
  23. package/docs/zh/configure/app/tools/sass.mdx +88 -16
  24. package/docs/zh/configure/app/tools/svgr.mdx +93 -0
  25. package/docs/zh/configure/app/tools/ts-checker.mdx +3 -17
  26. package/docs/zh/guides/basic-features/render/ssr-cache.mdx +14 -1
  27. package/docs/zh/guides/basic-features/static-assets/svg-assets.mdx +29 -17
  28. package/docs/zh/guides/get-started/ultramodern.mdx +42 -14
  29. package/docs/zh/plugin/introduction.mdx +1 -1
  30. package/docs/zh/plugin/server-plugins/api.mdx +1 -0
  31. package/package.json +19 -17
  32. package/ultramodern-preset/package.json +3 -3
package/docs/zh/guides/basic-features/render/ssr-cache.mdx CHANGED
@@ -39,7 +39,7 @@ export interface CacheControl {
39
39
  }
40
40
  ```
41
41
 
42
- 其中 `customKey` 为自定义缓存 key。默认情况下 Modern.js 将会把请求 `pathname` 作为 key 进行缓存，但在某些情况下这不能满足你的需求，开发者可以进行自定义。
42
+ 其中 `customKey` 为自定义缓存 key。默认情况下，缓存 key 由请求的 origin、归一化后的 pathname（去除末尾斜杠）以及 query 组成。当设置了 `customKey` 后，它会完全替代默认 key：`customKey` 回调函数接收的是归一化后的 pathname（而非 `CacheOptionProvider` 的 `req`），并需要自行负责整个分区（例如按租户、host 或 query 区分）——不能将原始 cookie 或其他凭证嵌入返回的 key 中。
43
43
 
44
44
  **Function 类型**
45
45
 
@@ -111,6 +111,19 @@ export const cacheOption: CacheOption = {
111
111
 
112
112
  上述 `/home` 和 `/about` 将会作为模式进行匹配，这意味着 `/home/abc` 也会匹配上该规则。同时，你也可以在其中编写正则语法：`/home/.+`
113
113
 
114
+ ### 缓存策略
115
+
116
+ 以下策略由框架自动执行，返回的 `CacheControl` 无法覆盖：
117
+
118
+ - 只有 `GET` 请求会被缓存。
119
+ - 请求携带 `Cookie` 或 `Authorization` 请求头时会跳过缓存，除非设置了 `customKey`（自定义 key 被视为一份明确的分区约定）。
120
+ - 请求的 `Cache-Control` 为 `private`、`no-cache` 或 `no-store` 时会跳过缓存。
121
+ - 只有当响应为 `200`、`Cache-Control` 中不含 `private`/`no-cache`/`no-store`、不含 `Set-Cookie`、也不含非空的 `Vary` 头时才会被写入缓存；否则会删除该 key 已有的缓存条目，而不是写入新的。
122
+ - 当 `stale` 状态触发的重新渲染结果不再可缓存时（例如变为按用户区分），本次已返回的 stale 响应不受影响，但缓存条目会被清除，后续请求将不再命中该缓存。
123
+ - `CacheOptionProvider` 返回 `false` 依然会完全禁用该请求的缓存，不受上述策略影响。
124
+
125
+ 缓存 key 带有命名空间（`__ssr__cache:v2:...`）。旧版本未加命名空间的缓存条目（包括自定义 `Container` 中已存储的条目）不会再被读取，只会依据容器自身的淘汰/TTL 机制自然过期；不存在全局缓存清空操作。
126
+
114
127
  ### 缓存容器
115
128
 
116
129
  默认情况下，Server 将会使用内存进行缓存。但通常情况下服务将会部署在 Serverless 容器上。每一次的服务访问可能都是一个新的进程，这样每次访问都不能应用缓存。
package/docs/zh/guides/basic-features/static-assets/svg-assets.mdx CHANGED
@@ -42,16 +42,22 @@ export default () => <Logo />;
42
42
 
43
43
  ## 修改默认导出
44
44
 
45
- 你可以通过 [output.svgDefaultExport](/configure/app/output/svg-default-export) 配置项来修改 SVG 文件默认导出的内容，比如把默认导出的内容设置为 React 组件：
45
+ 你可以通过 [tools.svgr](/configure/app/tools/svgr) 的 `svgrOptions.exportType` 来修改 SVG 文件默认导出的内容，比如把默认导出的内容设置为 React 组件：
46
46
 
47
47
  ```ts
48
48
  export default {
49
- output: {
50
- svgDefaultExport: 'component',
49
+ tools: {
50
+ svgr: {
51
+ svgrOptions: {
52
+ exportType: 'default',
53
+ },
54
+ },
51
55
  },
52
56
  };
53
57
  ```
54
58
 
59
+ 旧的 [output.svgDefaultExport](/configure/app/output/svg-default-export) 配置项仍然生效，但已废弃。
60
+
55
61
  此时再使用默认导入，你会得到一个 React 组件，而不是 URL：
56
62
 
57
63
  ```tsx title="src/component/Logo.tsx"
@@ -80,12 +86,12 @@ export default () => <Logo />;
80
86
 
81
87
  默认情况下，在 JS 文件中引用 SVG 资源时，Modern.js 会调用 SVGR，将 SVG 图片转换为一个 React 组件。
82
88
 
83
- 如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用时，可以通过将 [disableSvgr](/configure/app/output/disable-svgr) 设置为 true 来关闭此项转换，以提升构建性能。
89
+ 如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用时，可以通过将 [tools.svgr](/configure/app/tools/svgr) 设置为 `false` 来关闭此项转换，以提升构建性能。
84
90
 
85
91
  ```js
86
92
  export default {
87
- output: {
88
- disableSvgr: true,
93
+ tools: {
94
+ svgr: false,
89
95
  },
90
96
  };
91
97
  ```
@@ -153,21 +159,27 @@ declare module '*.svg' {
153
159
  }
154
160
  ```
155
161
 
156
- 如果需要修改 SVGR 配置，可通过如下方式：
162
+ 如果需要修改 SVGR 配置，可通过 [tools.svgr](/configure/app/tools/svgr) 的 `svgrOptions` 设置。传入的 `svgoConfig.plugins` 会按插件名与默认配置深度合并，因此只需写出要改动的部分：
157
163
 
158
164
  ```js
159
165
  export default {
160
166
  tools: {
161
- bundlerChain: (chain, { CHAIN_ID }) => {
162
- chain.module
163
- .rule(CHAIN_ID.RULE.SVG)
164
- .oneOf(CHAIN_ID.ONE_OF.SVG)
165
- .use(CHAIN_ID.USE.SVGR)
166
- .tap(options => {
167
- // modify svgoConfig
168
- options.svgoConfig.plugins[0].params.overrides.removeUselessDefs = false;
169
- return options;
170
- });
167
+ svgr: {
168
+ svgrOptions: {
169
+ svgoConfig: {
170
+ plugins: [
171
+ {
172
+ name: 'preset-default',
173
+ params: {
174
+ overrides: {
175
+ // 在默认的 preset-default 之上追加一项 override
176
+ removeUselessDefs: false,
177
+ },
178
+ },
179
+ },
180
+ ],
181
+ },
182
+ },
171
183
  },
172
184
  },
173
185
  };
package/docs/zh/guides/get-started/ultramodern.mdx CHANGED
@@ -49,13 +49,44 @@ CLI 按当前契约创建、扩展和验证 workspace。
49
49
  ## 创建并验证 Workspace
50
50
 
51
51
  ```bash
52
- pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical
52
+ pnpm dlx @bleedingdev/modern-js-ultramodern-create@<V> my-workspace --renderer react
53
+ cd my-workspace
53
54
  mise install
54
55
  mise exec -- pnpm install
55
56
  mise exec -- pnpm check
56
57
  mise exec -- pnpm build
57
58
  ```
58
59
 
60
+ 将 `<V>` 替换为已发布的框架版本。省略 `--renderer` 时使用 React；首次生成时
61
+ 也可选择 `solid` 或 `octane`。添加应用的命令从 `modern.config.ts` 读取选择，
62
+ 不接受 `--renderer`。
63
+
64
+ ### 选择应用渲染器
65
+
66
+ 使用 fork 的配置入口，由它注册所选渲染器的插件组合：
67
+
68
+ ```ts title="modern.config.ts"
69
+ import { defineConfig } from '@modern-js/ultramodern-app-tools';
70
+
71
+ export default defineConfig({
72
+ renderer: 'solid', // 也可选 'react' 或 'octane'；省略时使用 'react'
73
+ server: { ssr: true },
74
+ });
75
+ ```
76
+
77
+ Solid 2.0.0-rc.13 和 Octane 是 Node 预览配置，支持 CSR、原生流式 SSR、
78
+ hydration 和框架管理的文件路由。使用 Node 26.7.0 或更新版本。组件使用
79
+ `solid-js` / `@solidjs/web` 或 `octane` 的原生语法；路由原语从
80
+ `@modern-js/renderer-solid/router` 或 `@modern-js/renderer-octane/router`
81
+ 导入。生成的入口负责挂载和 hydration。更改渲染器后，需要匹配的原生源码和
82
+ 依赖，并重启开发服务器、重新加载页面。
83
+
84
+ 原生预览配置不支持 workers、Module Federation、RSC、SSG、React i18n
85
+ 集成、SVG 组件导入，以及在业务源码旁生成 CSS 类型声明；SVG URL 导入仍可使用。
86
+ [应用工具 README](https://github.com/BleedingDev/ultramodern.js/tree/main/packages/solutions/ultramodern-app-tools#readme)
87
+ 列出当前预览配置及固定依赖版本。下文的 federation、i18n 和 Cloudflare 示例
88
+ 适用于 React 配置。
89
+
59
90
  本地化 Cloudflare SSR workspace 在服务端将 `/` 重定向到协商的语言路径。
60
91
  `Accept-Language: cs-CZ` 返回 `302`、`Location: /cs`、
61
92
  `Cache-Control: private, no-store`，以及覆盖语言检测 Header 的 `Vary`。
@@ -65,25 +96,22 @@ curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
65
96
  ```
66
97
 
67
98
  严格 Effect 生成 workspace 会通过 pnpm overrides 固定兼容版本组：
68
- `effect@4.0.0-rc.112`、`@effect/opentelemetry@4.0.0-rc.112` 和
69
- `@effect/vitest@4.0.0-rc.112`。不要添加与这些 overrides 冲突的 app 本地直接
99
+ `effect@4.0.0-rc.117`、`@effect/opentelemetry@4.0.0-rc.117` 和
100
+ `@effect/vitest@4.0.0-rc.117`。不要添加与这些 overrides 冲突的 app 本地直接
70
101
  Effect 版本。严格的 24 小时发布年龄门禁适用于实际安装的包；当前版本组不包含 Effect
71
102
  年龄豁免，仅用于 override 的 `@effect/vitest` 也不是已安装的审批目标。
72
- `trustPolicyExclude` 是独立策略，仅为 `effect` 和
73
- `@effect/opentelemetry` 保留精确例外，以处理 trusted-publisher metadata 向
74
- provenance attestation 的迁移；它不属于 release-age 审批。
75
103
 
76
104
  ### 当前生成依赖基线
77
105
 
78
106
  | 范围 | 固定版本 |
79
107
  | --- | --- |
80
- | Effect runtime 与测试版本组 | `effect`、`@effect/opentelemetry`、`@effect/vitest`：`4.0.0-rc.112` |
81
- | Effect compiler | `@effect/tsgo@0.41.0` |
82
- | Oxc 与 Ultracite | `oxlint@1.81.0`、`oxfmt@0.66.0`、`ultracite@7.11.0` |
83
- | TanStack Router | `@tanstack/react-router@1.170.33`、`@tanstack/router-core@1.171.28`、`@tanstack/history@1.162.2` |
84
- | Module Federation | `bridge-react`、`manifest`、`modern-js-v3`、`rspack`：`2.9.0`；`@module-federation/node@2.7.50` |
108
+ | Effect runtime 与测试版本组 | `effect`、`@effect/opentelemetry`、`@effect/vitest`：`4.0.0-rc.117` |
109
+ | Effect compiler | `@effect/tsgo@0.45.0` |
110
+ | Oxc 与 Ultracite | `oxlint@1.85.0`、`oxfmt@0.70.0`、`ultracite@7.12.0` |
111
+ | TanStack Router | `@tanstack/react-router@1.170.41`、`@tanstack/router-core@1.171.34`、`@tanstack/history@1.162.4` |
112
+ | Module Federation | `bridge-react`、`manifest`、`modern-js-v3`、`rspack`：`2.9.2`；`@module-federation/node@2.7.52` |
85
113
  | Tailwind CSS | `tailwindcss@4.3.3` |
86
- | Node 与包管理工具 | Node `26.7.0`、`@types/node@^26.4.1`、pnpm `11.24.0` |
114
+ | Node 与包管理工具 | Node `26.7.0`、`@types/node@^26.6.2`、pnpm `11.27.1` |
87
115
 
88
116
  生成的 workspace 默认使用 `@module-federation/bridge-react` 的
89
117
  router-free base entry（`bridge.enableBridgeRouter: false`），应用路由由
@@ -160,11 +188,11 @@ migration 时不要再用 app 本地 postprocess。Cloudflare public output 默
160
188
 
161
189
  ## 配置公开预设
162
190
 
163
- 在标准 Modern.js `defineConfig` 调用中使用
191
+ 在 UltraModern `defineConfig` 调用中使用
164
192
  `presetUltramodern(appConfig, presetOptions)`：
165
193
 
166
194
  ```ts title="modern.config.ts"
167
- import { defineConfig, presetUltramodern } from '@modern-js/app-tools';
195
+ import { defineConfig, presetUltramodern } from '@modern-js/ultramodern-app-tools';
168
196
 
169
197
  export default defineConfig(
170
198
  presetUltramodern(
package/docs/zh/plugin/introduction.mdx CHANGED
@@ -129,7 +129,7 @@ Rsbuild 是 Modern.js 底层的构建工具，通过添加 Rsbuild 插件可修
129
129
  | 插件 | 介绍 | Modern.js 链接 |
130
130
  | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
131
131
  | [React 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-react) | 提供对 React 的支持 | - |
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) |
132
+ | [SVGR 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-svgr) | 支持将 SVG 图片转换为一个 React 组件 | [tools.svgr](/configure/app/tools/svgr) |
133
133
  | [Assets Retry 插件](https://github.com/rstackjs/rsbuild-plugin-assets-retry) | 用于在静态资源加载失败时自动发起重试请求 | [output.assetsRetry](/configure/app/output/assets-retry.html) |
134
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
135
  | [Source Build 插件](https://github.com/rstackjs/rsbuild-plugin-source-build) | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新 | [experiments.sourceBuild](/configure/app/experiments/source-build.html) |
package/docs/zh/plugin/server-plugins/api.mdx CHANGED
@@ -191,6 +191,7 @@ api.onPrepare(async () => {
191
191
  - `'file-change'`： 文件变化事件
192
192
  - `event.payload`： 当 `type` 为 `'file-change'` 时，包含文件变化信息数组。
193
193
  - **执行阶段：** 当文件发生变化或需要重新打包时。
194
+ - **重新打包顺序：** 对于 `'repack'`，开发服务器会按注册顺序等待处理函数完成，再从 require 缓存中清除上一代服务端产物。某个处理函数抛出错误时，其后的处理函数不再执行。新请求会等待处理函数完成；已在执行的请求继续使用已加载的模块。重新打包处理函数不能等待发往开发服务器的请求，因为该请求会等待处理函数完成。
194
195
  - **示例：**
195
196
 
196
197
  ```typescript
package/package.json CHANGED
@@ -2,13 +2,13 @@
2
2
  "name": "@bleedingdev/modern-js-main-doc",
3
3
  "description": "Documentation for the UltraModern.js framework",
4
4
  "type": "module",
5
- "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
5
+ "homepage": "https://github.com/ultramodernjs/ultramodern.js#readme",
6
6
  "bugs": {
7
- "url": "https://github.com/BleedingDev/ultramodern.js/issues"
7
+ "url": "https://github.com/ultramodernjs/ultramodern.js/issues"
8
8
  },
9
9
  "repository": {
10
10
  "type": "git",
11
- "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
11
+ "url": "git+https://github.com/ultramodernjs/ultramodern.js.git",
12
12
  "directory": "packages/document"
13
13
  },
14
14
  "license": "MIT",
@@ -19,32 +19,31 @@
19
19
  "modern.js",
20
20
  "ultramodern.js"
21
21
  ],
22
- "version": "3.9.0-ultramodern.9",
22
+ "version": "3.9.3-ultramodern.2",
23
23
  "publishConfig": {
24
24
  "access": "public"
25
25
  },
26
26
  "dependencies": {
27
- "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.9",
28
- "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.9",
29
- "mermaid": "^11.17.2"
27
+ "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.3-ultramodern.2",
28
+ "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.3-ultramodern.2",
29
+ "mermaid": "^12.0.0"
30
30
  },
31
31
  "devDependencies": {
32
32
  "@rsbuild/plugin-sass": "2.0.1",
33
- "@rspress/core": "2.0.21",
34
- "@rspress/plugin-llms": "2.0.21",
35
- "@rspress/shared": "2.0.21",
36
- "@shikijs/transformers": "^4.4.3",
33
+ "@rspress/core": "2.0.23",
34
+ "@rspress/plugin-llms": "2.0.23",
35
+ "@rspress/shared": "2.0.23",
36
+ "@shikijs/transformers": "^4.5.0",
37
37
  "@types/fs-extra": "11.0.4",
38
- "@types/node": "^26.4.1",
39
- "@typescript/native-preview": "7.0.0-dev.20260707.2",
38
+ "@types/node": "^26.6.3",
40
39
  "classnames": "^2.5.1",
41
40
  "clsx": "^2.1.1",
42
- "fs-extra": "^11.4.0",
43
- "react": "^19.2.8",
44
- "react-dom": "^19.2.8",
41
+ "fs-extra": "^11.4.1",
42
+ "react": "^19.3.0",
43
+ "react-dom": "^19.3.0",
45
44
  "rsbuild-plugin-open-graph": "1.1.3",
46
45
  "ts-node": "^10.9.2",
47
- "typescript": "^7.0.2"
46
+ "typescript": "7.0.2"
48
47
  },
49
48
  "nx": {
50
49
  "targets": {
@@ -66,5 +65,8 @@
66
65
  "dev:no_lazy": "LAZY=false rspress dev",
67
66
  "build": "rspress build",
68
67
  "preview": "rspress preview"
68
+ },
69
+ "ultramodern": {
70
+ "sourceName": "@modern-js/main-doc"
69
71
  }
70
72
  }
package/ultramodern-preset/package.json CHANGED
@@ -7,13 +7,13 @@
7
7
  "test": "node --test tests/*.test.ts"
8
8
  },
9
9
  "engines": {
10
- "node": ">=26.7.0"
10
+ "node": ">=26.10.0"
11
11
  },
12
12
  "dependencies": {
13
13
  "rsbuild-plugin-open-graph": "1.1.3"
14
14
  },
15
15
  "devDependencies": {
16
- "@rspress/core": "2.0.21",
17
- "@types/node": "^26.4.1"
16
+ "@rspress/core": "2.0.23",
17
+ "@types/node": "^26.6.3"
18
18
  }
19
19
  }