@modern-js/main-doc 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @modern-js/main-doc
 
+## 2.10.0
+
+### Patch Changes
+
+- 92d247f: fix: support tools.devServer.header include string[] type, remove get & delete & apply api in hook or middleware api
+  fix: 支持 tools.devServer.header 包含字符串数组类型，移除 Hook 和 Middleware 中对 响应 Cookie 的获取、删除操作
+- 19e552a: fix: main doc theme
+
+  fix: 首页深色模式问题
+
+- Updated dependencies [cfdbf80]
+  - @modern-js/builder-doc@2.10.0
+
 ## 2.9.0
 
 ### Patch Changes

package/docs/en/apis/app/runtime/web-server/hook.mdx

@@ -38,9 +38,7 @@ type HookContext = {
     set: (key: string, value: string) => void;
     status: (code: number) => void;
     cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
+      set: (key: string, value: string, options?: any) => void;
       clear: () => void;
     };
     raw: (

package/docs/en/apis/app/runtime/web-server/middleware.mdx

@@ -46,11 +46,8 @@ type MiddlewareContext = {
     set: (key: string, value: string) => void;
     status: (code: number) => void;
     cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
+      set: (key: string, value: string, options?: any) => void;
       clear: () => void;
-      apply: () => void;
     };
     raw: (
       body: string,

package/docs/en/blog/index.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+---
+
+# Blog
+
+You can find the latest news about Modern.js here.
+

package/docs/en/configure/app/output/splitRouteChunks.mdx

@@ -0,0 +1,20 @@
+---
+sidebar_label: splitRouteChunks
+---
+
+# output.splitRouteChunks
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+When using convention-based routing, the framework will split js and css based on the route to load on demand. If your project does not want to split js and css based on routes, you can set this option to `false`.
+
+Example:
+
+```ts
+export default {
+  output: {
+    splitRouteChunks: false,
+  },
+}
+```

package/docs/en/guides/advanced-features/compatibility.mdx

@@ -75,4 +75,5 @@ Visit the page `http://localhost:8080/__polyfill__` on Chrome 51 to see:
 :::caution
 This feature only works when using Modern.js built-in Web Server.
 
+If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through html.template / tools.html will cause this feature not work.
 :::

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -4,7 +4,7 @@ sidebar_position: 1
 
 # Using Rspack
 
-import Rspack from '@modern-js/builder-doc/docs/en/shared/rspack.md';
+import Rspack from '@modern-js/builder-doc/docs/en/shared/rspack-tip.mdx';
 
 <Rspack />
 

package/docs/en/guides/get-started/introduction.mdx

@@ -9,7 +9,7 @@ sidebar_position: 1
 
 Currently, Modern.js includes three solutions, each targeting at different development scenarios: web application development, npm package development, and document site development:
 
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/Solutions-en-1311.png)
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/Solutions-en-0945.png)
 
 As a part of the Modern.js engineering system, each of these solutions can be used separately and has its own independent documentation site. Developers can choose one or more solutions as needed.
 

package/docs/en/guides/get-started/quick-start.mdx

@@ -139,6 +139,8 @@ The bundle is generated to `dist/` by default, and the directory structure is as
     └── js
 ```
 
+> If you want to customize the output directory, please refer to [Output Files](https://modernjs.dev/builder/en/guide/basic/output-files.html).
+
 ## Verify
 
 Execute `pnpm run serve` in the project to verify locally that the bundle is running correctly:

package/docs/en/guides/topic-detail/framework-plugin/plugin-api.mdx

@@ -2,6 +2,7 @@
 title: Plugin API
 sidebar_position: 6
 ---
+
 # Plugin API
 
 The `setup` function of the plugin will receive an `api` imported parameter, and you can call some methods provided on the api to obtain information such as configuration and application context.
@@ -36,17 +37,40 @@ interface UserConfig {
   source?: SourceConfig;
   output?: OutputConfig;
   server?: ServerConfig;
-  dev?: DevConfig;
   deploy?: DeployConfig;
-  tools?: ToolsConfig;
-  plugins?: PluginConfig;
-  runtime?: RuntimeConfig;
-  runtimeByEntries?: RuntimeByEntriesConfig;
+  // ...other fields
+}
+```
+
+Please refer to [Configuration](/configure/app/usage) for the specific meanings of configuration fields.
+
+:::tip
+This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use [config hook](/guides/topic-detail/framework-plugin/hook-list.html#config).
+:::
+
+### useResolvedConfigContext
+
+Used to retrieve the final configuration after parsing.
+
+```ts
+const useResolvedConfigContext: () => NormalizedConfig;
+
+interface NormalizedConfig {
+  source: NormalizedSourceConfig;
+  output: NormalizedOutputConfig;
+  server: NormalizedServerConfig;
+  deploy: NormalizedDeployConfig;
+  _raw: UserConfig; // the original user config
+  // ...other fields
 }
 ```
 
 Please refer to [Configuration](/configure/app/usage) for the specific meanings of configuration fields.
 
+:::tip
+This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use [config hook](/guides/topic-detail/framework-plugin/hook-list.html#config).
+:::
+
 ### useAppContext
 
 Used to retrieve the runtime context of the application.
@@ -75,29 +99,6 @@ interface IAppContext {
 }
 ```
 
-### useResolvedConfigContext
-
-Used to retrieve the final configuration after parsing.
-
-```ts
-const useResolvedConfigContext: () => NormalizedConfig;
-
-interface NormalizedConfig {
-  source: NormalizedSourceConfig;
-  output: OutputConfig;
-  server: ServerConfig;
-  dev: DevConfig;
-  deploy: DeployConfig;
-  tools: NormalizedToolsConfig;
-  plugins: PluginConfig;
-  runtime: RuntimeConfig;
-  runtimeByEntries?: RuntimeByEntriesConfig;
-  _raw: UserConfig;
-}
-```
-
-Please refer to [Configuration](/configure/app/usage) for the specific meanings of configuration fields.
-
 ### useHookRunners
 
 Used to retrieve the executor of Hooks and trigger the execution of specific Hooks.

package/docs/en/guides/topic-detail/generator/codesmith/api/fs.mdx

@@ -12,8 +12,8 @@ API wrapper for file operations in microgenerators, providing methods to render
 import { FsAPI } from '@modern-js/codesmith-api-fs';
 
 export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const handlebarApi = new HandlebarsAPI(generator);
-  await handlebarsAPI.renderFile(
+  const fsApi = new FsAPI(generator);
+  await fsApi.renderFile(
      material.get('templates/a.js'),
      target: 'b.js'
    );

package/docs/zh/apis/app/runtime/web-server/hook.mdx

@@ -36,9 +36,7 @@ type HookContext = {
     set: (key: string, value: string) => void;
     status: (code: number) => void;
     cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
+      set: (key: string, value: string, options?: any) => void;
       clear: () => void;
     };
     raw: (

package/docs/zh/apis/app/runtime/web-server/middleware.mdx

@@ -45,11 +45,8 @@ type MiddlewareContext = {
     set: (key: string, value: string) => void;
     status: (code: number) => void;
     cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
+      set: (key: string, value: string, options?: any) => void;
       clear: () => void;
-      apply: () => void;
     };
     raw: (
       body: string,

package/docs/zh/blog/index.md

@@ -1,6 +1,74 @@
 ---
-title: Modern.js 2.0
+sidebar_position: 1
 ---
-# Modern.js 2.0
 
-> 即将到来
+# 博客
+
+在这里，你可以了解到 Modern.js 的最新进展和技术分享。
+
+---
+
+## Modern.js v2 发布：支持 Rspack 构建
+
+> 发表于 2023.03.16
+
+大家好，很高兴地向大家宣布，Modern.js v2 版本已经正式发布了！
+
+Modern.js 是字节跳动 Web Infra 团队开源的一套 Web 工程体系。在开源以来的一年多时间里，Modern.js 保持稳定的迭代节奏，数十位贡献者参与了开发，累计提交 2000+ 个 Pull Request，并支持了 Rspack 构建、嵌套路由、流式渲染等新特性。
+
+在这篇文章里，我们会和大家一起聊一聊 Modern.js 在过去一年多时间里的变化。
+
+[了解更多 →](/blog/updates/v2-release-note)
+
+---
+
+## React Streaming SSR 原理解析
+
+> 发表于 2022.12.16
+
+React 18 提供了一种新的 SSR 渲染模式： Streaming SSR。通过 Streaming SSR，我们可以实现以下两个功能：
+
+- Streaming HTML：服务端可以分段传输 HTML 到浏览器，而不是像 React 18 以前一样，需要等待服务端渲染完成整个页面后才返回给浏览器。这样，浏览器可以更快的启动 HTML 的渲染，提高 FP、FCP 等性能指标。
+- Selective Hydration：在浏览器端 hydration 阶段，可以只对已经完成渲染的区域做 hydration，而不需要等待整个页面渲染完成、所有组件的 JS bundle 加载完成，才能开始 hydration。这样可以更早的对已经完成渲染的区域做事件绑定，从而让页面获得更好的可交互性。
+
+[了解更多 →](https://mp.weixin.qq.com/s/w4FS5sBcHqRl-Saqi19Y6g)
+
+---
+
+## React Server Component 介绍
+
+> 发表于 2022.12.01
+
+React 官方对 Server Component 是这样介绍的: **zero-bundle-size React Server Components**。
+
+这是一种实验性探索，但相信该探索是个未来 React 发展的方向，与 React Server Component 相关的周边生态正在积极的建设当中。
+
+[了解更多 →](https://mp.weixin.qq.com/s/B-XLvW00vl5RE1Ur3EW4ow)
+
+---
+
+## 2022 年 9 ~ 10 月更新内容
+
+> 发表于 2022.11.01
+
+Modern.js 9 ~ 10 月的最新版本为 v1.21.0，本双月的主要更新有：
+
+- **支持 pnpm v7**：完成框架对 pnpm v7 的支持。
+- **服务端增加 Typescript 作为 ts 文件编译器**。
+
+[了解更多 →](/blog/updates/2022-0910-updates)
+
+---
+
+## 2022 年 7 ~ 8 月更新内容
+
+> 发表于 2022.09.05
+
+Modern.js 7 ~ 8 月的最新版本为 v1.17.0，本双月的主要更新有：
+
+- **支持 React 18**：完成框架和插件对 React 18 的适配。
+- **包版本统一**：Modern.js 所有组成包的版本号进行统一，提供升级命令。
+- **模块工程支持 bundle 构建**：模块工程类型的项目，支持对产物做 bundle 构建。
+- **Reduck v1.1**：发布 Reduck v1.1，使用文档全面更新。
+
+[了解更多 →](/blog/updates/2022-0708-updates)

package/docs/zh/blog/updates/2022-0708-updates.md

@@ -0,0 +1,96 @@
+---
+sidebar_position: 99
+---
+
+# 2022 年 7 ~ 8 月更新内容
+
+> 发表于 2022.09.05
+
+Modern.js 7 ~ 8 月的最新版本为 v1.17.0，本双月的主要更新有：
+
+- **支持 React 18**：完成框架和插件对 React 18 的适配。
+- **包版本统一**：Modern.js 所有组成包的版本号进行统一，提供升级命令。
+- **模块工程支持 bundle 构建**：模块工程类型的项目，支持对产物做 bundle 构建。
+- **Reduck v1.1**：发布 Reduck v1.1，使用文档全面更新。
+
+## 支持 React 18
+
+Modern.js 框架和相关插件完成对 React 18 的适配。现在，只需要将项目中的 `react`、`react-dom` 两个包的版本，升级到最新的 React 18 大版本，就可以使用 React 18 的新功能。
+
+注意，使用 `@modern-js/create` 命令默认创建的项目，安装的依赖 `react`、`react-dom` 的版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本。
+
+另外，SSR 流式渲染功能，目前尚在开发中，暂不支持。
+
+## Modern.js 包版本统一
+
+之前，组成 Modern.js 的各个包的版本号并不统一，Modern.js 自身的版本和这些包的版本缺少明确的对应关系。这不仅增加了我们的维护成本，而且给用户的使用和升级带来了很多困扰。
+
+从 v1.15.0 版本开始，Modern.js 自身的版本号和所有组成包的版本号，进行了统一。例如，Modern.js v1.15.0，意味着所有组成包的版本号也是 v1.15.0。 每次发布新版本，Modern.js 所有包都会使用统一的版本号执行发布。 Github 上仓库的 [tag](https://github.com/modern-js-dev/modern.js/tags) 编号和 Modern.js 所有组成包的版本号是一一对应的。
+
+我们提供了专门的升级工具： `@modern-js/upgrade`，可以自动升级 Modern.js 到当前的最新版本。使用方式为，在项目根路径下执行：
+
+```bash
+npx @modern-js/upgrade
+```
+
+## 模块工程支持 bundle 构建
+
+模块工程（ `@modern-js/module-tools` ）对底层实现进行重构，新增 [`output.buildConfig`](https://modernjs.dev/v1/docs/apis/module/config/output/build-config/) 配置，用于提供更加丰富的构建功能。
+
+新的模块工程项目，不仅支持对产物做 bundless 构建，也支持 bundle 构建。通过配置 `buildConfig` 下的 [`buildType`](https://modernjs.dev/v1/docs/apis/module/config/output/build-config/build-type) ，即可进行 bundle 构建：
+
+```ts
+// modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  output: {
+    buildConfig: {
+      buildType: 'bundle', // 采用 bundle 构建
+    },
+  },
+});
+```
+
+`buildConfig` 下还支持 [`bundleOptions`](https://modernjs.dev/v1/docs/apis/module/config/output/build-config/bundle-options) 配置，可以对构建行为做更多的自定义：如设置产物文件名、是否进行代码分片、设置代码压缩方式等。
+
+## Reduck v1.1
+
+Reduck 作为 Modern.js 的第一方状态管理方案，发布 v1.1 版本，增加对 React 18 Concurrent Rendering 的支持，并对开发体验和功能稳定性做了大量优化。
+
+新增 API：
+
+- [`useStore`](https://modernjs.dev/v1/docs/apis/app/runtime/model/use-store) ：可以在组件内获取当前组件树共享的 Store，满足在组件外访问 Model 的场景需求。
+- [`handleEffect`](https://modernjs.dev/v1/docs/apis/app/runtime/model/handle-effect)：一个工具函数，可以极大地简化异步数据获取的逻辑代码。
+- [`connect`](https://modernjs.dev/v1/docs/apis/app/runtime/model/connect)： HOC 风格的 API，用于访问 Model。
+
+开发体验方面，优化 Reduck 组成包的组织结构，减少用户侧依赖数量，现在只需要引入 `@modern-js-reduck/react` 一个包（Modern.js 中 Reduck 功能已内置，无需手动引入包）；优化 API 的 TS 类型定义，改进类型信息的自动推导，整体达到 TS 支持开箱即用。
+
+此外，对 Reduck [使用文档](https://modernjs.dev/v1/docs/guides/features/model/quick-start) 和 [API 文档](https://modernjs.dev/v1/docs/apis/app/runtime/model/model_) 做了全面更新，提供了更加丰富和详尽的内容。
+
+## 其他更新
+
+### 命令和配置
+
+**新增命令**
+
+- [`upgrade`](https://modernjs.dev/v1/docs/apis/app/commands/upgrade)：自动升级 Modern.js 版本。功能同执行 `npx @modern-js/upgrade` 命令。
+- [`inspect`](https://modernjs.dev/v1/docs/apis/app/commands/inspect)：通过该命令可以输出当前项目使用的完整 webpack 配置。
+- [`gen-release-note`](https://modernjs.dev/v1/docs/apis/module/commands/gen-release-note)：自动根据当前仓库的 [changesets](https://github.com/changesets/changesets) 信息生成发布日志。此外，我们提供了[包版本管理专题文档](https://modernjs.dev/v1/docs/guides/features/changesets/introduce)，方便大家更好的认识和使用 changesets 及相关功能。
+
+**新增配置**
+
+- [`source.preEntry`](https://modernjs.dev/v1/docs/apis/app/config/source/pre-entry)：用于配置全局脚本，这段脚本会早于页面的代码执行。
+
+### BFF
+
+- 新增 [`afterLambdaRegisted`](https://modernjs.dev/v1/docs/apis/app/runtime/bff-server/after-lambda-registed) hook。用于使用 Express 框架时，在 BFF 函数注册路由之后执行。可以用来添加错误处理逻辑，新增路由等。
+- 优化使用 Express 框架开发场景下的热更新性能。在比较大的项目中，BFF 函数更改，热更新也可以在几十毫秒内完成。
+
+### SSR
+
+- SSR 产物添加 Sourcemap，优化服务端调试 SSR 代码的体验。
+
+### Web Server
+
+- 支持按入口设置响应头，使用方式请参考[文档](https://modernjs.dev/v1/docs/apis/app/config/server/routes#自定义响应头)。

package/docs/zh/blog/updates/2022-0910-updates.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 98
+---
+
+# 2022 年 9 ~ 10 月更新内容
+
+> 发表于 2022.11.01
+
+Modern.js 9 ~ 10 月的最新版本为 v1.21.0，本双月的主要更新有：
+
+- **支持 pnpm v7**：完成框架对 pnpm v7 的支持。
+- **服务端增加 Typescript 作为 ts 文件编译器**。
+
+## 支持 pnpm v7
+
+Modern.js 框架完成了对 pnpm v7 的变更适配。
+
+使用 `npx @modern-js/create@modern-1` 创建项目时会根据用户当前环境的 pnpm 版本进行安装依赖操作，并且在初始化项目中会在 `.npmrc` 中添加
+`strict-peer-dependencies=false` 配置，避免安装时由于 `peerDependencies` 缺失导致安装依赖失败问题。
+同时适配 `release`、`deploy` 命令对 pnpm v7 的支持。
+
+pnpm v7 在命令传参方面姿势发生了变化，需注意：
+
+在使用 pnpm 调用 `package.json` 中的命令时，如果需要传递参数至 pnpm，需要将参数放到命令前。
+
+例如使用 pnpm `--filter` 参数执行 prepare 命令：
+
+```bash
+pnpm run --filter "./packages/**" prepare
+```
+
+如果需要传递参数至命令，需要将参数放到命令后。
+
+例如，在如下 `package.json` 配置中：
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+执行 command 命令时携带参数方式为：
+
+```bash
+pnpm run command --options
+```
+
+## 服务端增加 Typescript 作为 ts 文件编译器
+
+在 Modernjs 之前的版本中，我们为了保证前后端编译器的统一，使用了 Babel 作为前后端默认的编译器，并保持相同的编译逻辑，但随着使用的项目增多，我们发现在一些服务端常用的语法场景下，Babel 编译 ts 有一些问题。
+
+因此，我们将服务端编译 ts 的编译器由 Babel 改为了 Typescript，在别名解析逻辑上与 Babel 版本保持一致，同样支持使用 `tsconfig.json` 或者插件设置别名。
+
+在执行 build 命令时，已默认使用 Typescript 编译，并默认开启了类型校验，很多项目在 9、10 双月已经在使用。
+
+执行 dev 命令时，如果希望使用 Typescript 编译，需要安装 `ts-node`，`tsconfig-paths` 到 `devDependencies`，否则默认仍然使用 Babel 编译。在 Modern.js 2.0 中，我们将使用 ts-node 作为默认的编译器。
+
+## 其他更新
+
+### 配置更新
+
+- 支持在 `tools.webpackChain` 中获取 `HtmlWebpackPlugin` 对象，使用方式请参考[文档](https://modernjs.dev/v1/docs/apis/app/config/tools/webpack-chain#htmlwebpackplugin)。
+
+### 底层依赖升级
+
+- husky 升级至 v8
+
+使用 `npx @modern-js/create@modern-1` 创建项目时，husky 会默认安装 v8 版本，并移除 `package.json` 中 husky 的配置，使用 `.husky` 文件夹的形式管理 husky 配置。
+
+在初次安装依赖时需要执行 `npx husky install` 进行 husky 初始化，默认项目会在 prepare 命令中完成，如果 husky 配置未生效，可通过手动执行完成 husky 配置。
+
+## 功能预告
+
+Modern.js 团队目前除了正常开发维护 Modern 1.0 外，正在全力打造 Modern.js 2.0。
+
+Modern.js 2.0 将带来新的构建体系，除了支持使用稳定的 webpack 进行构建，还即将支持将底层构建工具切换为自研的 Rust bundler，提供更流畅的编译速度。
+
+Modern.js 2.0 将基于 [React-Router v6](https://reactrouter.com) 推荐嵌套路由作为新的路由方式；将默认支持 React 18 并提供 Streaming SSR 的支持，使用户体验更加流畅。

package/docs/zh/blog/updates/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "更新内容",
+  "position": 2,
+  "collapsed": false
+}