@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/guides/advanced-features/web-server.md

@@ -0,0 +1,135 @@
+---
+title: 扩展 Web Server
+sidebar_position: 2
+---
+
+有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等，这时，可以通过对 Modern.js 内置的 Web Server 进行扩展实现相应需求。
+
+## 创建定制 Web Server
+
+
+在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「Server 自定义」功能：
+
+
+```bash
+? 请选择你想要的操作： 创建工程元素
+? 创建工程元素： 新建「Server 自定义」源码目录
+? 请选择运行时框架： Express/Koa/Egg/Nest
+```
+
+目前 Modern.js 默认支持 4 种主流的 Node.js Server 框架：[Express](https://expressjs.com/)、[Koa](https://koajs.com/)、[Egg.js](https://eggjs.org/zh-cn/)、[Nest](https://nestjs.com/)，选择运行时框架时，可根据自身偏好进行选择。
+
+执行命令后，项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。
+
+## 框架差异
+
+由于不同框架 API 的差异性，自定义逻辑的写法也有所不同。假设有以下场景：当请求的 cookies 中包含 `login-token` 时，认为用户已登录，正常返回页面；否则返回 404 状态码。下面就以此场景为例，演示不同框架下如何实现定制 Web Server 逻辑。
+
+:::info 注
+目前 Modern.js 只支持前置中间件的扩展。
+:::
+
+### Express
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+import type { Request, Response, NextFunction } from 'express';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware((request: Request, response: Response, next: NextFunction) => {
+    if (request.headers.cookies['login-token']) {
+      return next();
+    } else {
+      response.status = 401;
+      response.end();
+    }
+  });
+});
+```
+
+### Koa
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+import type { Context, Next } from 'koa';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx: Context, next: Next) => {
+    if (ctx.cookies['login-token']) {
+      await next();
+    } else {
+      ctx.status = 401;
+    }
+  });
+});
+```
+
+### Egg
+
+Egg 添加中间件的方式与 Koa 相同。
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+import type { Context, Next } from 'koa';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx: Context, next: Next) => {
+    if (ctx.cookies['login-token']) {
+      await next();
+    } else {
+      ctx.status = 401;
+    }
+  });
+});
+```
+
+### Nest
+
+Nest 支持添加两种类型的内容：Express 的函数中间件和 Nest 中的 [Module](https:/docs.nestjs.com/modules)。
+
+Express 的函数中间件的添加与 Express 部分的示例相同，同时这里使用 Module 来为 Web Server 添加一条新的路由。
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+import { Module, Injectable, Controller, Get } from '@nestjs/common';
+
+@Controller('cats')
+export class CatsController {
+  constructor(private readonly catsService: CatsService) {}
+
+  @Get()
+  getHello() {
+    return this.catsService.getHello();
+  }
+}
+
+@Injectable()
+class CatsService {
+  getHello(): string {
+    return '<div>Hello world!</div>';;
+  }
+}
+
+@Module({
+  controllers: [CatsController],
+  providers: [CatsService],
+})
+class CatsModule {}
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware((request: Request, response: Response, next: NextFunction) => {
+    if (request.headers.cookies['login-token']) {
+      return next();
+    } else {
+      response.status = 401;
+      response.end();
+    }
+  });
+
+  addMiddleware(CatsModule);
+});
+```
+
+:::info 注
+Modern.js 中 Web Server 与应用是一体的，在开发调试、生产部署阶段都无需单独运维。
+:::

package/zh/guides/basic-features/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "基础功能",
+  "position": 3,
+  "collapsed": false,
+  "link": {
+    "type": "doc",
+    "id": "guides/basic-features/index"
+  }
+}

package/zh/guides/basic-features/alias.md

@@ -0,0 +1,67 @@
+---
+title: 别名
+sidebar_position: 8
+---
+
+Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块，并内置了以下别名:
+
+```js
+{
+  '@': '<appDirectory>/src',
+  '@shared': '<appDirectory>/shared',
+}
+```
+
+:::info 注
+在开启可选功能时，生成器也会动态的添加内置别名，例如启用 BFF 时默认会添加 `@api` 别名：
+:::
+
+`src/` 目录结构如下时，从 `src/App.tsx` 文件中导入 `src/common` 目录下的模块:
+
+```bash
+.
+├── common
+│   ├── styles
+│   │   └── base.css
+│   └── utils
+│       └── index.ts
+├── App.tsx
+```
+
+`src/App.tsx` 中写法如下:
+
+```ts
+import utils from '@/src/common/utils';
+import '@/src/common/styles/base.css';
+```
+
+Modern.js 也提供了自定义别名的方式，以添加 `@common` 别名为例，对于 TypeScript 项目，只需要在项目根目录 `tsconfig.json` 下配置 `compilerOptions.paths` 如下:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ],
+      "@/common/*": [
+        "./src/common/*"
+      ]
+    }
+  },
+}
+```
+
+JavaScript 项目可以在 `modern.config.js` 中配置 [`source.alias`](/docs/configure/app/source/alias):
+
+```js title="modern.config.js"
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common'
+    }
+  }
+});
+```
+
+具体别名配置可以参考 【[API 资料 - source.alias](/docs/configure/app/source/alias)】。

package/zh/guides/basic-features/css/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "CSS 开发方案",
+  "position": 3
+}

package/zh/guides/basic-features/css/css-in-js.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 1
+---
+
+# CSS-in-JS
+
+CSS-in-JS 是一种可以将 CSS 样式写在 JS 文件里的技术。Modern.js 集成了社区常用的 CSS-in-JS 实现库 [styled-components](https://styled-components.com/)，它使用 JavaScript 的新特性 [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) 编写组件的 CSS 样式。可以直接从 `@modern-js/runtime/styled` 引入 [styled-components](https://styled-components.com/) 的 API 进行使用。
+
+当需要编写一个内部字体为红色的 `div` 组件时，可以如下实现：
+
+```js
+import styled from '@modern-js/runtime/styled'
+
+const RedDiv = styled.div`
+  color: red;
+`
+```
+
+当需要根据组件的 `props` 动态设置组件样式时，例如 `props` 的属性 `primary` 为 `true` 时，按钮的颜色为白色，其他情况为红色，实现代码如下：
+
+```js
+import styled from '@modern-js/runtime/styled'
+
+const Button = styled.button`
+  color: ${props => props.primary ? "white" : "red"};
+  font-size: 1em;
+`
+```
+
+关于 styled-components 的更多用法，请参考【[styled-components 官网](https://styled-components.com/)】。
+
+:::info 补充信息
+Modern.js 内部使用了 Babel 插件 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components)，可以通过 [`tools.styledComponents`](/docs/configure/app/tools/styled-components) 对插件进行配置。
+:::
+
+:::tip 提示
+如果需要使用 [styled-jsx](https://www.npmjs.com/package/styled-jsx)、[Emotion](https://emotion.sh/) 等其他 CSS-in-JS 库，需要先安装对应库的依赖。具体使用方式请参考对应库的官网。
+:::

package/zh/guides/basic-features/css/css-modules.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 5
+---
+
+# CSS Modules
+
+Modern.js 为 [CSS Modules](https://github.com/css-modules/css-modules) 提供了开箱即用的支持。
+
+## 文件后缀形式 CSS Modules
+
+默认情况下，以 `.module.(css|scss|sass|less)` 结尾的文件会作为 CSS Modules 文件处理，例如：
+
+```css title="button.module.css"
+.redColor {
+  color: red;
+}
+```
+
+```js title="Button.jsx"
+import styles from './button.module.css';
+
+export default function Button() {
+  return (
+    <button type="button" className={styles.redColor}>
+      red button
+    </button>
+  );
+}
+```
+
+最终将被编译为
+
+```js
+<button type="button" className="button_redColor__1-RBg">
+  red button
+</button>;
+```
+
+## 全面启用 CSS Modules
+
+如果想去掉文件名中 `.module` 后缀，可以设置 [`output.disableCssModuleExtension`](/docs/configure/app/output/disable-css-module-extension)。
+
+设置后，除了 `node_modules/` 目录下的样式文件和文件名称格式为 `[name].global.(css|scss|sass|less)` 之外的所有样式文件，都会作为 CSS Modules 处理。
+
+如果此时需要全局样式，可以通过创建文件名称格式为 `[name].global.(css|less|scss|sass)` 的样式文件来解决， 例如:
+
+```css title="app.global.css"
+.bg-blue {
+  background-color: blue;
+}
+```
+
+```css title="button.css"
+.redColor {
+  color: red;
+}
+```
+
+```js title="App.jsx"
+import './app.global.css';
+import styles from './button.css';
+
+export default function Button() {
+  return (
+    <button type="button" className={`${styles.redColor} bg-blue`}>
+      button
+    </button>
+  );
+}
+```
+
+最终将被编译为:
+
+```js
+<button type="button" className="button__redColor--JsFYl bg-blue">
+  button
+</button>;
+```
+
+最终效果如下：
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/more-css-modules.png)
+
+:::tip 提示
+使用 [babel-plugin-react-css-modules](https://github.com/gajus/babel-plugin-react-css-modules) 时需要注意，该插件的配置选项 `generateScopedName` 需要和 [`output.cssModuleLocalIdentName`](/docs/configure/app/output/css-module-local-ident-name) 保持一致。
+:::

package/zh/guides/basic-features/css/less-sass.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 4
+---
+
+# Less 和 Sass
+
+[Less](https://lesscss.org/) 和 [Sass](https://sass-lang.com/) 是常用的两种 CSS 预处理器，Modern.js 通过插件来提供 Less 和 Sass 编译能力的支持。
+
+## 启用 Less 或 Sass
+
+为了使用 Less 或 Sass 编译能力，我们需要先启用对应的功能。
+
+以 Less 为例，在当前项目根目录执行 new 命令, 并选择 **启用 Less 支持** 即可。
+
+```bash
+$ pnpm run new
+? 请选择你想要的操作
+? 启用可选功能 (Use arrow keys)
+❯ 启用 Less 支持
+```
+
+## 自定义配置
+
+- 如果需要自定义 [less-loader](https://github.com/webpack-contrib/less-loader) 的配置，请参考 [tools.less](/docs/configure/app/tools/less) 配置项。
+- 如果需要自定义 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的配置，请参考 [tools.less](/docs/configure/app/tools/sass) 配置项。
+
+:::tip 提示
+经过 Less 和 Sass 预编译后的 CSS 文件，仍然会经过 Modern.js 内置的 [PostCSS](https://postcss.org/) 的转换，具备良好的浏览器兼容性。相关内容请参考【[PostCSS](/docs/guides/basic-features/css/postcss)】。
+:::

package/zh/guides/basic-features/css/postcss.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 3
+---
+
+# PostCSS
+
+[PostCSS](https://postcss.org/) 是一个用 JavaScript 工具和插件转换 CSS 代码的工具。Modern.js 内置 PostCSS，并集成 [Autoprefixer](https://github.com/postcss/autoprefixer) 等常用的 PostCSS 插件，能够满足大多数项目的样式开发需求。
+
+默认情况下，Modern.js 会对 CSS 进行以下编译和转换：
+
+1. [Autoprefixer](https://github.com/postcss/autoprefixer) 根据需要支持的浏览器范围，会自动为 CSS 规则添加需要的浏览器厂商前缀。Modern.js 默认支持的浏览器范围为：`['> 0.01%', 'not dead', 'not op_mini all']`。
+
+  :::info 注意
+    - 【支持的浏览器范围为：`> 0.01%`】是指浏览器市场份额大于 0.01%。
+    - `not dead` 是指不包含官方不再支持的浏览器和过去24个月没有更新的浏览器。
+    - `not op_mini all` 是指不包含 Opera Mini。
+  :::
+
+  :::info 补充信息
+    如果需要修改默认浏览器支持范围，可以在项目的 `package.json` 文件中配置 `browserslist`，设置规则参考 [Browserslist](https://github.com/browserslist/browserslist) 的使用，下面是一个示例：
+    ``` json title="package.json"
+    {
+      "browserslist": [
+        "last 1 version",
+        "> 1%",
+        "IE 10"
+      ]
+    }
+    ```
+  :::
+
+2. 提供 [CSS custom properties](https://www.w3.org/TR/css-variables-1/) 支持，可以在 CSS 中定义和使用自定义变量，如：
+
+  ```css
+  :root {
+    --main-bg-color: pink;
+  }
+
+  body {
+    background-color: var(--main-bg-color);
+  }
+  ```
+
+3. 提供 [CSS Nesting](https://drafts.csswg.org/css-nesting-1/) 支持，可以在 CSS 中使用嵌套写法，如：
+
+  ```css
+  table.colortable td {
+    text-align: center;
+  }
+  table.colortable td.c {
+    text-transform: uppercase;
+  }
+  ```
+  也可以改写成 CSS 嵌套写法：
+  ```css
+  table.colortable {
+    & td {
+      text-align: center;
+      &.c { text-transform: uppercase }
+    }
+  }
+  ```
+
+4. 修复已知的 [Flexbugs](https://github.com/philipwalton/flexbugs) 。
+5. 对以下 CSS 特性提供兼容：
+    - [`initial` 属性值](https://developer.mozilla.org/en-US/docs/Web/CSS/initial_value)
+    - [`break-` 属性](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after)
+    - [`font-variant`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)
+    - [Media Query Ranges](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#syntax_improvements_in_level_4)
+
+  当需要修改 PostCSS 配置时，可以通过底层配置 [`tools.postcss`](/docs/configure/app/tools/postcss) 来实现，下面是一个示例：
+
+```js title="modern.config.js"
+export default defineConfig({
+  tools: {
+    postcss: {
+      plugins: ['autoprefixer', ('postcss-flexbugs-fixes': {})],
+    },
+  },
+});
+```

package/zh/guides/basic-features/css/tailwindcss.md

@@ -0,0 +1,98 @@
+---
+sidebar_position: 2
+---
+
+# Tailwind CSS
+
+[Tailwind CSS](https://tailwindcss.com/) 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展。在 Modern.js 中使用 [Tailwind CSS](https://tailwindcss.com/)，只需要在项目根目录下执行 `pnpm run new` 并开启。
+
+按照如下进行选择：
+
+```bash
+? 请选择你想要的操作: 启用可选功能
+? 启用可选功能: 启用 Tailwind CSS 支持
+```
+
+使用时在入口的根组件(如 `src/App.jsx`)添加如下代码：
+
+```js
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+```
+
+然后即可在各个组件中使用 Tailwind CSS 提供的 Utility Class 了。
+
+:::info 补充信息
+根据不同需求，可以选择性的导入 Tailwind CSS 提供的 CSS 文件。由于使用 `@taiwind` 与直接导入 CSS 文件的作用等价，因此关于 Tailwind CSS 提供的 CSS 文件的用途，可以参考 [`@tailwind` 的使用](https://tailwindcss.com/docs/functions-and-directives#tailwind) 文档中注释里的内容。
+:::
+
+当需要自定义 Tailwind CSS 的 [theme](https://tailwindcss.com/docs/theme) 配置的时候，可以在配置 [`source.designSystem`](/docs/configure/app/source/design-system) 中修改，例如，颜色主题中增加一个 `primary`：
+
+```js title="modern.config.js"
+export default defineConfig({
+  source: {
+    designSystem: {
+      extend: {
+        colors: {
+          primary: '#5c6ac4',
+        },
+      },
+    },
+  },
+});
+```
+
+当需要对 Tailwind CSS 做 [theme](https://tailwindcss.com/docs/theme) 以外的其他特殊配置时，可以在 [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) 中配置，例如设置 `variants`：
+
+```js title="modern.config.js"
+export default defineConfig({
+  tools: {
+    tailwindcss: {
+      variants: {
+        extend: {
+          backgroundColor: ['active'],
+        },
+      },
+    },
+  },
+});
+```
+
+## 使用 [`Twin`](https://github.com/ben-rogerson/twin.macro) 库
+
+在上一章中介绍了什么是 CSS-in-JS 以及社区常用的 CSS-in-JS 库 [styled-components](https://styled-components.com/)。这一部分将要介绍如何通过 [`Twin`](https://github.com/ben-rogerson/twin.macro) 在 CSS-in-JS 中使用 [Tailwind CSS](https://tailwindcss.com/)。使用 [`Twin`](https://github.com/ben-rogerson/twin.macro) 可以更容易在 CSS-in-JS 的代码中使用 Tailwind CSS。[`Twin`](https://github.com/ben-rogerson/twin.macro) 对于自己的描述是：
+
+> *Twin blends the magic of Tailwind with the flexibility of css-in-js*
+
+在开启「Tailwind CSS 支持」的功能后，首先需要安装 [`Twin`](https://github.com/ben-rogerson/twin.macro) 依赖:
+
+``` bash
+# package manager is `pnpm`
+pnpm add twin.macro -D
+
+# package manager is `yarn`
+yarn add twin.macro -D
+```
+
+当项目安装 `twin.macro` 依赖后，Modern.js 会检测到该依赖并对内置的 `babel-plugin-macro` 增加 `twin.macro` 相关的配置。因此在安装完依赖后，无需手动配置。下面是一个简单使用 `twin.macro` 的示例：
+
+``` js
+import tw from 'twin.macro'
+
+const Input = tw.input`border hover:border-black`
+```
+
+:::tip 提示
+如果在运行过程中出现了 `MacroError: /project/App.tsx` 错误的时候，有可能是缺少 `twin.macro` 依赖导致的。
+:::
+
+更多的使用方式可以参考 `twin.macro` 的 [文档](https://github.com/ben-rogerson/twin.macro/blob/master/docs/index.md)。
+
+`twin.macro` 默认会读取项目目录下的 `tailwindcss.config.js` 文件，或者通过 `babel-plugin-macro` 上的 [`twin.config`](https://github.com/ben-rogerson/twin.macro/blob/master/docs/options.md#options) 指定的文件路径读取 Tailwind CSS 配置。不过在 Modern.js 中不需要进行这些额外配置。
+
+当在 `modern.config.ts` 文件中通过 [`source.designSystem`](/docs/configure/app/source/design-system) 和  [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) 对 Tailwind CSS 进行配置的时候，这些配置也会对 `twin.macro` 生效。
+> 当为项目配置 Tailwind CSS 的时候，[`source.designSystem`](/docs/configure/app/source/design-system) 和  [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) 这两个配置的组合等价于单独配置了一个 `tailwindcss.config.js` 文件。
+> 其中[`source.designSystem`](/docs/configure/app/source/design-system)等效于 Tailwind CSS 的 [`theme`](https://v2.tailwindcss.com/docs/configuration#theme) 配置。
+
+

package/zh/guides/basic-features/data-fetch.md

@@ -0,0 +1,4 @@
+---
+title: 数据获取
+sidebar_position: 2
+---

package/zh/guides/basic-features/env-vars.md

@@ -0,0 +1,83 @@
+---
+title: 环境变量
+sidebar_position: 7
+---
+
+## 使用环境变量
+
+默认情况下，在前端代码中可以直接使用 `NODE_ENV` 环境变量，如下:
+
+```js
+if (process.env.NODE_ENV === 'development') {
+  // do something
+}
+```
+
+执行 `dev` 命令之后可以看到构建产物如下:
+
+```js
+if (true) {
+  // do something
+}
+```
+
+同样在自定义的 HTML 模板中，也可以直接使用环境变量。如 `config/html/head.html`:
+
+```js
+<meta name="test" content="<process.env.NODE_ENV>">
+```
+
+如果想在代码中使用除 `NODE_ENV` 以外的环境变量，可以在 [`source.define`](/docs/configure/app/source/define) 配置指定, 如下:
+
+```js title="modern.config.js"
+export default defineConfig({
+  source: {
+    envVars: ['VERSION']
+  }
+})
+```
+
+`VERSION` 环境变量需要在编译之前设置好, 可以在执行命令时添加:
+
+```bash
+// linux, macOS
+$ VERSION=1.0.0 npm run dev
+
+// windows
+$ set VERSION=1.0.0&&npm run dev
+```
+
+Modern.js 也支持在 `.env` 文件中定义环境变量：
+
+```js title=".env"
+VERSION=1.0.0
+```
+
+更多文件格式：
+
+* `.env`：默认加载。
+* `.env.development`、`.env.test`、`.env.production`：针对具体环境设置环境变量，会覆盖 `.env` 中的设置。
+
+
+## 使用全局变量
+
+Modern.js 支持在编译时设置代码中使用到的全局变量:
+
+```js title="modern.config.js"
+export default defineConfig({
+  source: {
+    globalVars: {
+      VERSION: '1.0.0'
+    }
+  }
+})
+```
+
+在代码中可以直接使用:
+
+```ts title="App.tsx"
+/* TS 应用中，需要声明该变量 */
+declare const VERSION: string;
+
+const a = VERSION;
+```