@modern-js/main-doc 2.8.0 → 2.10.0

package/docs/en/tutorials/first-app/c03-css.mdx

@@ -0,0 +1,323 @@
+---
+title: Add Style
+---
+# Add Style
+
+import { Tabs, Tab as TabItem } from "@theme";
+
+In the previous chapter, we learned how to use components from the three-way library.
+
+In this chapter, we will learn how to implement UI components.
+
+## JS components using CSS
+
+First of all, we want to control the display of contact avatars by ourselves, and implement this design draft:
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-expect.jpg)
+
+Hypothesis has no ready-made components to implement, so you need to write some CSS yourself. Here we use [styled-components] (https://styled-components.com/) to implement similar requirements. Modern.js out of the box supports styled-components, which requires neither dependency nor configuration.
+
+Style-components avoids many problems of traditional CSS writing through modularization. For example, writing styles directly on the style attribute of elements, the visual details of UI will also be mixed with the details of UI structure and business logic. Or classname needs to avoid global space renaming, which requires the use of naming conventions.
+
+Modify the code at the top in `src/routes/page.tsx`:
+
+```js
+import styled from '@modern-js/runtime/styled';
+```
+
+Add the following code:
+
+```js
+const Avatar = styled.img`
+  width: 50px;
+  height: 50px;
+  border: 4px solid #0ef;
+  border-radius: 50%;
+`;
+```
+
+Modify the code of `List.Item.Meta`:
+
+```tsx
+<List.Item.Meta
+  avatar={<Avatar src={avatar} />}
+  title={name}
+  description={email}
+/>
+```
+
+Execute `pnpm run dev` to see the expected running result:
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-result1.png)
+
+Next we do a little refactoring. To enhance legibility and make the code easier to maintain, we can split the Avatar component. We execute the following command at the end point to create a new file:
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/components/Avatar
+touch src/components/Avatar/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/components/Avatar
+ni src/components/Avatar/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+Delete the `<Avatar>` implementation in `src/routes/page.tsx` and change it to:
+
+```ts
+import Avatar from '../components/Avatar';
+```
+
+The content of `src/components/Avatar/index.tsx` is modified to:
+
+```ts
+import styled from '@modern-js/runtime/styled';
+
+const Avatar = styled.img`
+  width: 50px;
+  height: 50px;
+  border: 4px solid #0ef;
+  border-radius: 50%;
+`;
+
+export default Avatar;
+```
+
+Execute `pnpm run dev`, the result should be the same.
+
+:::info note
+The reason for using the directory form `Avatar/index.tsx` instead of the single-file form `Avatar.tsx` is that you can easily add sub-files inside the directory later, including dedicated resources (pictures, etc.), dedicated sub-components, CSS files, etc.
+
+:::
+
+## Utility
+
+We have used the style-components implementation `<Avatar>` component, but the current UI is still unsatisfactory and lacks professionalism, such as the list item inhouse layout is a bit rough and misaligned in many places.
+
+Now, let's implement a better `Item` component ourselves, implementing a design draft like this:
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/design2.png)
+
+The UI to be implemented this time is more complex and has an internal structure, but on the other hand, there is no very thick bright blue border of the `<Avatar>` component such a very special UI, which is a very conventional horizontal and vertical layout, centering, font style, etc. In this case, there is actually no need to write CSS at all. There is a more efficient implementation method that complements styled-components: **Utility Class**.
+
+Modern.js integrates the mainstream, light, general-purpose Utility Class library [Tailwind CSS](https://tailwindcss.com/).
+
+Execute `pnpm run new` and select the following to start Tailwind CSS:
+
+```bash
+? Action: Enable features
+? Enable features: Enable Tailwind CSS
+```
+
+Register the Tailwind plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+  plugins: [appTools(), tailwindcssPlugin()],
+});
+```
+
+Import the Tailwind CSS css file at the top of `src/routes/page.tsx` to start a quick implementation of the professional UI:
+
+```js
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+```
+
+Create the Item component first:
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/components/Item
+touch src/components/Item/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/components/Item
+ni src/components/Item/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+Modify `src/routes/page.tsx` to pass the `render` implementation of `List` to `Item` component:
+
+```js
+import { List } from 'antd';
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import Item from '../components/Item';
+
+const getAvatar = (users: Array<{ name: string, email: string }>) =>
+  users.map(user => ({
+    ...user,
+    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
+  }));
+
+const mockData = getAvatar([
+  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
+  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
+  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
+  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
+]);
+
+function Index() {
+  return (
+    <div className="container lg mx-auto">
+      <List
+        dataSource={mockData}
+        renderItem={info => <Item key={info.name} info={info} />}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+Utility Class(https://tailwindcss.com/docs/container) is used on the parent container for a quick implementation of the most basic maximum width, center, and other styles.
+
+Next implementation `src/components/Item/index.tsx`:
+
+```tsx
+import Avatar from '../Avatar';
+
+type InfoProps = {
+  avatar: string;
+  name: string;
+  email: string;
+  archived?: boolean;
+};
+
+const Item = ({ info }: { info: InfoProps }) => {
+  const { avatar, name, email, archived } = info;
+  return (
+    <div className="flex p-4 items-center border-gray-200 border-b">
+      <Avatar src={avatar} />
+      <div className="ml-4 flex-1 flex justify-between">
+        <div className="flex-1">
+          <p>{name}</p>
+          <p>{email}</p>
+        </div>
+        <button
+          type="button"
+          disabled={archived}
+          className={`bg-blue-500  text-white font-bold
+            py-2 px-4 rounded-full hover:bg-blue-700`}
+        >
+          Archive
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default Item;
+```
+
+Execute `pnpm run dev` to see the expected running result:
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result2.png)
+
+We only use a few Utility Classes, such as [Flex](https://tailwindcss.com/docs/display/), [Padding](https://tailwindcss.com/docs/padding/), [Margin](https://tailwindcss.com/docs/margin/), [Text](https://tailwindcss.com/docs/text-color/), [Font](https://tailwindcss.com/docs/font-weight/), [Border](https://tailwindcss.com/docs/border-width), without writing a single CSS implementation Professional UI that conforms to the design draft.
+
+## Customized Utility Class
+
+We can also implement the new Utility Class ourselves to facilitate reuse between codes.
+
+Utility Class itself is also a **component-oriented** technology (using different classes on a component is equivalent to setting some attributes from the base class for this component), but the classname of Utility Class is global (because it is used on arbitrary components/elements), it is very suitable for implementation with separate CSS files.
+
+Create a new CSS file:
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/styles
+touch src/styles/utils.css
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/styles
+ni src/styles/utils.css
+```
+
+</TabItem>
+</Tabs>
+
+Import `utils.css` in `src/routes/page.tsx`:
+
+```js
+import '../styles/utils.css';
+```
+
+A Utility Class named `custom-text-gray` is implemented in `src/routes/styles/utils.css`.
+
+```css
+:root {
+  --custom-text-color: rgb(113, 128, 150);
+}
+
+.custom-text-gray {
+  color: var(--custom-text-color);
+}
+```
+
+:::info note
+Modern.js integrates with [PostCSS](/guides/basic-features/css) and supports modern CSS syntax features such as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
+
+:::
+
+Use in `src/routes/components/Item/index.tsx`:
+
+```js
+<div className="ml-4 flex-1 flex justify-between">
+```
+
+Change to:
+
+```js
+<div className="ml-4 custom-text-gray flex-1 flex justify-between">
+```
+
+Execute `pnpm run dev`, you can see that the font color has changed:
+
+![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result3.png)
+
+:::info note
+This is just to demonstrate Utility Class usage. In a real project, with Tailwind CSS, this Utility Class is of little value and should be added to the font color through the [**theme**](https://tailwindcss.com/docs/customizing-colors) of the configuration Design System.
+
+`utils.css` can also be written as `utils.scss` or `utils.less`, Modern.js out of the box support for SCSS and Less.
+
+However, with the support of PostCSS, modern CSS should be sufficient to meet these development needs, and the performance is also better than that of the preprocessor. It is recommended to use `.css` files first.
+
+:::

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

@@ -0,0 +1,130 @@
+---
+title: Hook
+---
+# Hook
+
+用于拓展 Modern.js 内置的 Web Server，所有的页面请求都会经过 Hook。
+
+:::note
+更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
+:::
+
+## 使用姿势
+
+```ts
+import { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatchHook = (context, next) => {};
+export const afterRender: AfterRenderHook = (context, next) => {};
+```
+
+:::info 自定义 Web Server
+使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Serve」源码目录。
+
+```bash
+pnpm run new
+? 请选择你想要的操作 创建工程元素
+? 新建「自定义 Web Server」源码目录
+```
+:::
+
+## 函数签名
+
+```ts
+type HookContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    cookies: {
+      set: (key: string, value: string, options?: any) => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+  };
+  request: {
+    url: string;
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+};
+
+function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
+```
+
+另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AfterMatch` 和 `AfterRender` 两个 Hook。
+
+```ts
+type AfterMatchContext = HookContext & {
+  router: {
+    redirect: (url: string, status: number) => void;
+    rewrite: (entry: string) => void;
+  };
+};
+
+type AfterRenderContext = {
+  template: {
+    get: () => string;
+    set: (html: string) => void;
+    prependHead: (fragment: string) => void;
+    appendHead: (fragment: string) => void;
+    prependBody: (fragment: string) => void;
+    appendBody: (fragment: string) => void;
+  };
+};
+```
+
+### 参数
+
+- `context`：提供当前 Hook 上下文。
+  - `response`：提供一系列处理响应的操作
+  - `request`：提供一系列获取请求信息的操作
+  - `router`：提供对响应路由的快捷操作
+  - `template`：提供对响应内容的快捷操作
+- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
+
+## 示例
+
+### Redirect
+
+将页面重定向到站点外的页面，例如跳转到统一登录页：
+
+```ts
+import type { AfterMatch } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatch = async (ctx, next) => {
+  ctx.router.redirect('https://website.com/login', 302);
+};
+```
+
+### Rewrite
+
+将页面重写到当前站点的其他页面，例如同一个路由根据 UA 返回适配不同端的页面：
+
+```ts
+import type { AfterMatch } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatch = async (ctx, next) => {
+  ctx.router.rewrite('mobile');
+};
+```
+
+### HTML 内容注入
+
+为页面注入某些与渲染主体无关的 HTML 内容，如脚本、页面骨架等：
+
+```ts
+import type { AfterRender } from '@modern-js/runtime/server';
+
+export const afterRender: AfterRenderHook = (context, next) => {
+  ctx.template.prependBody('<div>Footer</div>');
+};
+```

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

@@ -0,0 +1,128 @@
+---
+title: Middleware
+---
+# Middleware
+
+用于拓展 Modern.js 内置的 Web Server，与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以直接操作 Node 原生的请求、响应对象，并且可以使用框架拓展。
+
+:::note
+更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
+:::
+
+## 使用姿势
+
+```ts
+import { Middleware } from '@modern-js/runtime/server';
+
+export const middleware: Middleware = async (context, next) => {};
+export const middleware: Middleware[] = [
+  async (context, next) => {},
+  async (context, next) => {},
+];
+```
+
+:::info 自定义 Web Server
+使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Server」源码目录。
+
+```bash
+pnpm run new
+? 请选择你想要的操作 创建工程元素
+? 新建「自定义 Web Server」源码目录
+```
+
+:::
+
+## 函数签名
+
+```ts
+type Middleware = (
+  context: MiddlewareContext,
+  next: NextFunction,
+) => Promise<void> | void;
+
+type MiddlewareContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    cookies: {
+      set: (key: string, value: string, options?: any) => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+    locals: Record<string, any>;
+  };
+  request: {
+    url: string;
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+  source: {
+    req: IncomingMessage;
+    res: ServerResponse;
+  };
+};
+```
+
+### 参数
+
+- `context`：提供当前 Hook 上下文。
+  - `response`：提供一系列处理响应的操作
+  - `request`：提供一系列获取请求信息的操作
+  - `source`：提供 Node.js 原生的 `req` 与 `res` 对象。
+- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
+
+:::warning
+`next` 函数的执行不影响后续内置流程，只控制下一个中间件是否执行。只有当响应被写入时，后续渲染流程才会中断。
+:::
+
+## 示例
+
+### 服务端耗时打点
+
+```ts
+export const Middleware = () => async (ctx, next) => {
+  const start = Date.now();
+  ctx.res.once('finish', () => {
+    console.log(Date.now() - start);
+  });
+};
+```
+
+### 注入服务端工具 & 数据
+
+Modern.js 提供了 `res.locals` 属性用来存放当前请求的局部变量。
+
+```ts
+export const Middleware = () => async (ctx, next) => {
+  ctx.res.locals.id = 'Modern.js';
+  ctx.res.locals.rpc = createRpcInstance();
+};
+```
+
+### 框架拓展
+
+Middleware 还可以和 BFF 一样，使用运行时框架拓展。Modern.js 约定，当使用框架运行时拓展时，类型信息从 `@modern-js/runtime/{namespace}` 下导出，Middleware 可以使用框架语法，例如框架中间件写法，以下是伪代码：
+
+```ts
+import { SomeType } from '@modern-js/runtime/{namespace}';
+
+export const middleware: SomeType = (ctx, next) => {
+  console.log(ctx.url);
+  next();
+};
+```
+
+默认情况下，在安装框架拓展插件后，Web Server 的框架拓展能力是关闭的。如果希望使用框架拓展，可以通过 [`server.enableFrameworkExt`](/configure/app/server/enable-framework-ext.html) 开启。
+
+:::info
+框架拓展导出的类型名不一定为 Middleware，命名由框架拓展插件。
+:::

package/docs/zh/apis/monorepo/commands/new.mdx

@@ -0,0 +1,39 @@
+---
+sidebar_position: 1
+---
+# new
+
+```bash
+Usage: modern new [options]
+
+Monorepo 创建子项目
+
+Options:
+  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
+  -c, --config <config>  生成器运行默认配置(JSON 字符串)
+  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
+  --registry             生成器运行过程中定制 npm Registry
+  -h, --help             display help for command
+```
+
+`modern new` 命令在 monorepo 中可以用来添加应用工程和可复用的模块：
+
+```bash
+$ modern new
+? 请选择你想创建的工程类型 (Use arrow keys)
+❯ Web 应用
+  Web 应用（测试）
+  Npm 模块
+  Npm 模块（内部）
+```
+
+应用工程默认会添加到 `apps` 目录， 测试应用会添加到 `examples` 目录，公共模块默认会添加到 `packages` 目录， 内部模块默认会添加到 `features` 目录。
+
+内部模块在 monorepo 的应用里面使用时，可以无需构建直接使用源码。
+
+:::caution 注意
+`--config` 参数对应参数值需要使用 JSON 字符串。
+
+pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
+
+:::

package/docs/zh/blog/index.md

@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+---
+
+# 博客
+
+在这里，你可以了解到 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)