@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

package/docs/zh/plugin/official/rsbuild-plugins/plugin-esbuild.mdx

@@ -1,201 +0,0 @@
----
-sidebar_position: 3
----
-
-# Esbuild 插件
-
-:::warning
-**当前文档中的 esbuild 功能已停止迭代**，我们更推荐使用 Rspack + SWC 的方案，因为 Rspack + SWC 具备更好的构建性能、功能丰富度和产物兼容性。
-
-请参考[「使用 Rspack」](guides/advanced-features/rspack-start)了解更多。
-
-:::
-
-import Esbuild from '@site-docs/components/esbuild.mdx';
-
-<Esbuild />
-
-## 快速开始
-
-### 在 Modern.js 框架中使用
-
-Modern.js 框架默认集成了 esbuild 插件，因此，你不需要手动安装和注册插件，只需要使用 [tools.esbuild](/configure/app/tools/esbuild.html) 配置项即可：
-
-```js
-export default defineConfig({
-  tools: {
-    esbuild: {
-      loader: {
-        target: 'chrome61',
-      },
-      minimize: {
-        target: 'chrome61',
-      },
-    },
-  },
-});
-```
-
-## 配置
-
-插件默认会开启代码转译和代码压缩的功能，你也可以通过配置来自定义插件的行为。
-
-### loader
-
-- **类型：**
-
-```ts
-type LoaderOptions = EsbuildLoaderOptions | false | undefined;
-```
-
-- **默认值：**
-
-```ts
-const defaultOptions = {
-  target: 'es2015',
-  charset: builderConfig.output.charset,
-};
-```
-
-这个选项用于启用 JavaScript 和 TypeScript 的转译，启用时将会使用 esbuild-loader 替换 babel-loader 和 ts-loader。
-
-如果你需要修改转译参数，可以查看 [esbuild-loader 文档](https://github.com/privatenumber/esbuild-loader#loader)。
-
-#### 设置 JSX 格式
-
-在使用 esbuild 进行代码转译时，esbuild 默认会读取 `tsconfig.json` 中的 `compilerOptions.jsx` 字段，来决定使用哪种 JSX 语法。
-
-因此，你需要在 `tsconfig.json` 中设置正确的 JSX 语法。
-
-比如 React 项目，需要将 `compilerOptions.jsx` 设置为 `react-jsx`：
-
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx"
-  }
-}
-```
-
-#### 修改目标环境
-
-通过 `target` 选项来修改代码转译的目标环境。`target` 可以直接设置为 JavaScript 语言版本，比如 `es6`，`es2020`；也可以设置为若干个目标环境，每个目标环境都是一个环境名称后跟一个版本号，比如 `['chrome58', 'edge16' ,'firefox57']`。`target` 字段的详细介绍可以参考 [esbuild - target](https://esbuild.github.io/api/#target)。
-
-target 支持设置为以下环境：
-
-- chrome
-- edge
-- firefox
-- ie
-- ios
-- node
-- opera
-- safari
-
-```ts
-builderPluginEsbuild({
-  loader: {
-    target: 'chrome61',
-  },
-});
-```
-
-#### 关闭代码转译
-
-将 `loader` 设置为 `false` 来关闭 esbuild 代码转译，此时 Modern.js 会继续使用 Babel 来进行代码转译。
-
-```ts
-builderPluginEsbuild({
-  loader: false,
-});
-```
-
-### minimize
-
-- **类型：**
-
-```ts
-type MinimizeOptions = EsbuildMinifyOptions | false | undefined;
-```
-
-- **默认值：**
-
-```ts
-const defaultOptions = {
-  css: true,
-  target: 'es2015',
-  format: builderTarget === 'web' ? 'iife' : undefined,
-};
-```
-
-这个选项用于启用 JavaScript 和 CSS 的代码压缩。
-
-如果你需要修改压缩参数，可以查看 [esbuild-loader 文档](https://github.com/privatenumber/esbuild-loader#minifyplugin)。
-
-#### 修改目标环境
-
-通过 `target` 选项来修改代码压缩的目标环境。
-
-```ts
-builderPluginEsbuild({
-  minimize: {
-    target: 'chrome61',
-  },
-});
-```
-
-#### 关闭代码压缩
-
-将 `minimize` 设置为 `false` 来关闭 esbuild 代码压缩，此时 Modern.js 会继续使用 Terser 进行代码压缩。
-
-```ts
-builderPluginEsbuild({
-  minimize: false,
-});
-```
-
-## esbuild 局限性
-
-虽然 esbuild 能给现有的 webpack 项目带来明显的构建性能提升，但这个工具在接入 Modern.js 时还存在一定的局限性，需要大家在接入的时候格外注意。
-
-### 兼容性
-
-使用 esbuild 进行代码转译时（即 `loader` 能力），esbuild 通常最低支持到 ES2015（即 ES6）语法，并且不具备自动注入 Polyfill 的能力。如果生产环境需要降级到 ES5 及以下的语法，建议使用 SWC 编译。
-
-你可以通过如下的配置指定目标语法版本:
-
-```ts
-builderPluginEsbuild({
-  loader: {
-    target: 'es2015',
-  },
-});
-```
-
-使用 esbuild 进行代码压缩时（即 `minimize` 能力），esbuild 可以在生产环境中进行压缩和混淆，通常最低支持到 ES2015 语法。
-
-如果设置压缩的 `target` 为 `es5`，需要保证所有代码已经被转义为 ES5 代码，否则会导致 esbuild 编译报错：`Transforming 'xxx' to the configured target environment ("es5") is not supported yet`。
-
-因此，对于生产环境需要兼容 ES5 及以下语法的项目，请谨慎开启 minimize 能力，建议使用 SWC 压缩。
-
-你可以通过如下的配置指定目标语法版本:
-
-```ts
-builderPluginEsbuild({
-  minimize: {
-    target: 'es2015',
-  },
-});
-```
-
-### 不支持 Babel 插件
-
-使用 esbuild 进行代码转译时，诸如 `babel-plugin-import` 等原有 Babel 插件的语法编译功能在开启 esbuild 后无法使用。并且由于 Modern.js 底层使用的是 esbuild 的 `Transform API`，因此不支持使用额外 esbuild 插件来进行自定义编译过程。
-
-如果你有 `babel-plugin-import` 等 Babel 插件相关诉求，可以使用 SWC 插件。
-
-### 产物体积
-
-使用 esbuild 压缩虽然带来了构建效率上的提升，但 esbuild 的压缩比例是低于 terser 的，因此**构建产物的体积会增大**，请根据业务情况酌情使用。通常来说，esbuild 比较适合中后台等对体积不敏感的场景。
-
-对于压缩工具之间的详细对比，可以参考 [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks)。

package/docs/zh/plugin/official/rsbuild-plugins.mdx

@@ -1,3 +0,0 @@
-# 概览
-
-- [@modern-js/plugin-esbuild](/plugin/official/rsbuild-plugins/plugin-esbuild)：提供 esbuild 编译支持。

package/docs/zh/tutorials/first-app/c01-start.mdx

@@ -1,99 +0,0 @@
----
-title: 创建项目
----
-# 创建项目
-
-从这一章节开始，我们将进入实战教程部分。在实战教程中，我们将会从环境准备开始，从简单到复杂，一步一步搭建一个真实的项目。
-
-## 环境准备
-
-import Prerequisites from "@site-docs/components/prerequisites"
-
-<Prerequisites />
-
-## 初始化项目
-
-我们创建新的目录，通过命令行工具初始化项目：
-
-```bash
-mkdir myapp && cd myapp
-npx @modern-js/create@latest
-```
-
-import InitApp from "@site-docs/components/init-app"
-
-<InitApp />
-
-## 调试项目
-
-import DebugApp from "@site-docs/components/debug-app"
-
-<DebugApp />
-
-## 修改代码
-
-我们将原本的示例代码删除，替换成一个简单的联系人列表：
-
-```tsx title="src/routes/page.tsx"
-const getAvatar = (users: Array<{ name: string; email: string }>) =>
-  users.map(user => ({
-    ...user,
-    avatar: `https://api.dicebear.com/7.x/pixel-art/svg?seed=${user.name}`,
-  }));
-
-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 App() {
-  return (
-    <ul>
-      {mockData.map(({ name, avatar, email }) => (
-        <li key={name}>
-          <img src={avatar} width={60} height={60} /> ---
-          <span>{name}</span> ---
-          <span>{email}</span>
-        </li>
-      ))}
-    </ul>
-  );
-}
-
-export default App;
-```
-
-删除多余的 css 文件，保持目录没有多余的文件：
-
-```bash
-rm src/routes/index.css
-```
-
-因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动更新为：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvt/ljhwZthlaukjlkulzlp/screenshot-20221214-141909.png)
-
-此刻的页面还没有样式。下一章节将展开这部分的内容。
-
-## 开启 SSR
-
-接下来，我们修改项目中的 `modern.config.ts`，开启 SSR 能力：
-
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-    state: true,
-  },
-  server: {
-    ssr: true,
-  },
-  plugins: [appTools()],
-});
-```
-
-重新执行 `pnpm run dev`，可以发现项目已经在服务端完成了页面渲染。

package/docs/zh/tutorials/first-app/c02-component.mdx

@@ -1,60 +0,0 @@
----
-title: 编写 UI 组件
----
-
-# 编写 UI 组件
-
-上一章节中，我们学习了如何初始化项目，并使用配置修改 Modern.js 的默认行为。
-
-这一章节中，我们继续沿用上一章节的项目代码，继续完善联系人列表。
-
-为了做更好的 UI 展示和交互，我们引入组件库 [Antd](https://ant.design/index-cn) 来开发，使用 `<List>` 组件来代替原始的列表。先添加依赖：
-
-import { PackageManagerTabs } from '@theme';
-
-<PackageManagerTabs command="add antd" />
-
-修改 `src/routes/page.tsx`，在顶部导入组件：
-
-```ts
-import { List } from 'antd';
-```
-
-修改 `<App>` 组件的实现：
-
-```tsx
-function App() {
-  return (
-    <div>
-      <List
-        dataSource={mockData}
-        renderItem={({ name, email, avatar }) => (
-          <List.Item key={name}>
-            <List.Item.Meta
-              avatar={<img alt="avatar" src={avatar} width={60} height={60} />}
-              title={name}
-              description={email}
-            />
-          </List.Item>
-        )}
-      />
-    </div>
-  );
-}
-```
-
-执行 `pnpm run dev`，查看运行结果：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c02-antd-result.png)
-
-可以看到 Ant Design 导出的组件，已经具备了完整的样式。
-
-:::info
-Modern.js 会[自动按需导入 Ant Design 组件需要的 CSS](https://github.com/ant-design/babel-plugin-import)。
-
-:::
-
-:::note
-我们也可以使用其他组件库来实现同样的功能，例如 [Arco Design](https://arco.design/)。
-
-:::

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

@@ -1,323 +0,0 @@
----
-title: 添加样式
----
-# 添加样式
-
-import { Tabs, Tab as TabItem } from "@theme";
-
-上一章节中，我们学习了如何使用使用三方库中的组件。
-
-这一章节中，我们将学习如何实现 UI 组件。
-
-## 使用 CSS 写 JS 组件
-
-首先我们希望自己控制联系人头像的展示，实现这种设计稿：
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-expect.jpg)
-
-假设没有现成的组件可以实现，那就需要自己写些 CSS 了，这里我们使用 [styled-components](https://styled-components.com/)，来实现类似的需求。Modern.js 开箱即用的支持 styled-components，既不需要安装依赖，也不需要做任何配置。
-
-styled-components 通过模块化的方式，避免了传统 CSS 写法上的诸多问题。例如直接在元素的 style 属性上写样式，UI 视觉上的细节也会跟 UI 结构上的细节和业务逻辑混在一起。或是 classname 需要避免全局空间重名，需要用到命名规范的问题。
-
-在 `src/routes/page.tsx` 里修改顶部的代码：
-
-```js
-import styled from '@modern-js/runtime/styled';
-```
-
-添加以下代码：
-
-```js
-const Avatar = styled.img`
-  width: 50px;
-  height: 50px;
-  border: 4px solid #0ef;
-  border-radius: 50%;
-`;
-```
-
-修改 `List.Item.Meta` 的代码：
-
-```tsx
-<List.Item.Meta
-  avatar={<Avatar src={avatar} />}
-  title={name}
-  description={email}
-/>
-```
-
-执行 `pnpm run dev`，可以看到预期的运行结果：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-result1.png)
-
-接下来我们做一点重构，为了增强可读性，让代码更容易维护，可以把 Avatar 组件拆分出去。我们在终端执行以下命令，创建新的文件：
-
-<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>
-
-把 `src/routes/page.tsx` 里的 `<Avatar>` 实现删掉，修改为：
-
-```ts
-import Avatar from '../components/Avatar';
-```
-
-`src/components/Avatar/index.tsx` 的内容，修改为：
-
-```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;
-```
-
-执行 `pnpm run dev`，运行结果应该是一样的。
-
-:::info
-采用目录形式 `Avatar/index.tsx` 而不是单文件形式 `Avatar.tsx` 的原因是，之后可以方便的在目录内部增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等。
-
-:::
-
-## 使用 Utility
-
-我们已经使用 style-components 实现 `<Avatar>` 组件，但当前的 UI 仍然不能让人满意，缺乏专业感，例如列表项内部的布局有点粗糙，很多地方没对齐。
-
-现在，我们自己来实现一个更好的 `Item` 组件，实现这样的设计稿：
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/design2.png)
-
-这次要实现的 UI 更复杂，有内部结构，但另一方面，并没有 `<Avatar>` 组件的**很粗的亮蓝色边框**这样很特殊的 UI，都是很常规的水平垂直布局、居中、字体样式等。这种情况下，其实根本没必要写 CSS，有更高效的、跟 styled-components 互补的实现方式：**Utility Class**。
-
-Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind CSS](https://tailwindcss.com/)。
-
-执行 `pnpm run new`，进行如下选择，开启 Tailwind CSS：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用 「Tailwind CSS」 支持
-```
-
-在 `modern.config.ts` 中注册 Tailwind 插件:
-
-```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()],
-});
-```
-
-在 `src/routes/page.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
-
-```js
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-```
-
-先创建 Item 组件：
-
-<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>
-
-修改 `src/routes/page.tsx`，把 `List` 的 `render` 实现交给 `Item` 组件：
-
-```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://api.dicebear.com/7.x/pixel-art/svg?seed=${user.name}`,
-  }));
-
-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) ，快速实现了最基本的最大宽度、居中等样式。
-
-接下来实现 `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;
-```
-
-执行 `pnpm run dev`，可以看到预期的运行结果：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result2.png)
-
-我们只使用了少量 Utility Class，比如 [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)，不写一行 CSS 就实现了符合设计稿的专业 UI。
-
-## 自定义 Utility Class
-
-我们也可以自己实现新的 Utility Class，方便在代码间复用。
-
-Utility Class 本身也是一种**面向组件**的技术（将不同 class 用在一个组件上，等价于给这个组件设置了一些来自基类的属性），但 Utility Class 的 classname 是全局的（因为要用在任意组件/元素上），很适合用独立 CSS 文件来实现。
-
-创建一个新的 CSS 文件：
-
-<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>
-
-在 `src/routes/page.tsx` 里导入 `utils.css`：
-
-```js
-import '../styles/utils.css';
-```
-
-在 `src/routes/styles/utils.css` 里实现一个名为 `custom-text-gray` 的 Utility Class。
-
-```css
-:root {
-  --custom-text-color: rgb(113, 128, 150);
-}
-
-.custom-text-gray {
-  color: var(--custom-text-color);
-}
-```
-
-:::info
-Modern.js 集成了 [PostCSS](/guides/basic-features/css/css)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)。
-
-:::
-
-在 `src/routes/components/Item/index.tsx` 里使用，把：
-
-```js
-<div className="ml-4 flex-1 flex justify-between">
-```
-
-改成：
-
-```js
-<div className="ml-4 custom-text-gray flex-1 flex justify-between">
-```
-
-执行 `pnpm run dev`，可以看到字体颜色改变了：
-
-![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result3.png)
-
-:::info
-此处只是为了演示 Utility Class 用法。真实项目中，在有 Tailwind CSS 的情况下，这种 Utility Class 没什么价值，应该通过配置 Design System 的 [**theme**](https://tailwindcss.com/docs/customizing-colors) 来增加字体颜色。
-
-`utils.css` 也可以写成 `utils.scss` 或 `utils.less`，Modern.js 对 SCSS 和 Less 同样提供开箱即用的支持。
-
-不过在 PostCSS 的支持下，现代 CSS 应该足以满足这些开发需求，性能相较于预处理器也更好，建议优先用 .css 文件。
-
-:::