@modern-js/main-doc 2.8.0 → 2.9.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/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/components/default-mwa-generate.mdx

@@ -0,0 +1,5 @@
+```bash
+? 请选择你想创建的工程类型：Web 应用
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+```

package/docs/zh/components/init-app.mdx

@@ -0,0 +1,44 @@
+Modern.js 生成器会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
+
+```bash
+? 请选择你想创建的工程类型：Web 应用
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+```
+
+在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。
+
+```bash
+[INFO] 依赖自动安装成功
+[INFO] git 仓库初始化成功
+[INFO] 创建成功！
+可在新项目的目录下运行以下命令：
+pnpm run dev          # 按开发环境的要求，运行和调试项目
+pnpm run build        # 按生产环境的要求，构建项目
+pnpm run serve        # 按生产环境的要求，运行项目
+pnpm run lint         # 检查和修复所有代码
+pnpm run new          # 继续创建更多项目要素，比如应用入口
+```
+
+:::note
+Modern.js 生成器除了在项目初始化时工作外，也能在后续研发中生成项目各种粒度的模块，并非一用即抛开。
+
+:::
+
+现在，项目结构如下：
+
+```
+.
+├── node_modules
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── modern.config.ts
+├── package.json
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```

package/docs/zh/components/init-rspack-app.mdx

@@ -0,0 +1,7 @@
+```bash
+$ npx @modern-js/create myapp
+? 请选择你想创建的工程类型：Web 应用
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+? 请选择构建工具：Rspack
+```

package/docs/zh/components/prerequisites.mdx

@@ -0,0 +1,18 @@
+### Node.js
+
+import NodeVersion from '@modern-js/builder-doc/docs/zh/shared/nodeVersion.md';
+
+<NodeVersion />
+
+### pnpm
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
+
+```bash
+npm install -g pnpm@7
+```
+
+:::note
+Modern.js 同样支持使用 `yarn`、`npm` 进行依赖管理。
+
+:::

package/docs/zh/configure/app/dev/asset-prefix.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: assetPrefix
+---
+
+# dev.assetPrefix
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.assetPrefix](https://modernjs.dev/builder/api/config-dev.html#devassetprefix)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/assetPrefix.md';
+
+<Main />

package/docs/zh/configure/app/dev/before-start-url.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: beforeStartUrl
+---
+
+# dev.beforeStartUrl
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.beforeStartUrl](https://modernjs.dev/builder/api/config-dev.html#devbeforestarturl)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/beforeStartUrl.md';
+
+<Main />

package/docs/zh/configure/app/dev/hmr.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: hmr
+---
+
+# dev.hmr
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.hmr](https://modernjs.dev/builder/api/config-dev.html#devhmr)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/hmr.md';
+
+<Main />

package/docs/zh/configure/app/dev/host.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: host
+---
+
+# dev.host
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.host](https://modernjs.dev/builder/api/config-dev.html#devhost)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/host.md';
+
+<Main />

package/docs/zh/configure/app/dev/https.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: https
+---
+
+# dev.https
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.https](https://modernjs.dev/builder/api/config-dev.html#devhttps)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/https.md';
+
+<Main />

package/docs/zh/configure/app/dev/port.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: port
+---
+
+# dev.port
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.port](https://modernjs.dev/builder/api/config-dev.html#devport)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/port.md';
+
+<Main />

package/docs/zh/configure/app/dev/progress-bar.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: progressBar
+---
+
+# dev.progressBar
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.progressBar](https://modernjs.dev/builder/api/config-dev.html#devprogressbar)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/progressBar.md';
+
+<Main />

package/docs/zh/configure/app/dev/start-url.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: startUrl
+---
+
+# dev.startUrl
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [dev.startUrl](https://modernjs.dev/builder/api/config-dev.html#devstarturl)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/dev/startUrl.md';
+
+<Main />

package/docs/zh/configure/app/experiments/lazy-compilation.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: lazyCompilation
+---
+
+# experiments.lazyCompilation
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [experiments.lazyCompilation](https://modernjs.dev/builder/api/config-experiments.html#experimentslazycompilation)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/experiments/lazyCompilation.md';
+
+<Main />

package/docs/zh/configure/app/html/app-icon.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: appIcon
+---
+
+# html.appIcon
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.appIcon](https://modernjs.dev/builder/api/config-html.html#htmlappicon)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/appIcon.md';
+
+<Main />

package/docs/zh/configure/app/html/crossorigin.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: crossorigin
+---
+
+# html.crossorigin
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.crossorigin](https://modernjs.dev/builder/api/config-html.html#htmlcrossorigin)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/crossorigin.md';
+
+<Main />

package/docs/zh/configure/app/html/disable-html-folder.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: disableHtmlFolder
+---
+
+# html.disableHtmlFolder
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.disableHtmlFolder](https://modernjs.dev/builder/api/config-html.html#htmldisablehtmlfolder)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/disableHtmlFolder.md';
+
+<Main />

package/docs/zh/configure/app/html/favicon-by-entries.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: faviconByEntries
+---
+
+# html.faviconByEntries
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.faviconByEntries](https://modernjs.dev/builder/api/config-html.html#htmlfaviconbyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/faviconByEntries.md';
+
+<Main />

package/docs/zh/configure/app/html/favicon.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: favicon
+---
+
+# html.favicon
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.favicon](https://modernjs.dev/builder/api/config-html.html#htmlfavicon)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/favicon.md';
+
+<Main />

package/docs/zh/configure/app/html/inject-by-entries.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: injectByEntries
+---
+
+# html.injectByEntries
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.injectByEntries](https://modernjs.dev/builder/api/config-html.html#htmlinjectbyentries)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/injectByEntries.md';
+
+<Main />

package/docs/zh/configure/app/html/inject.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: inject
+---
+
+# html.inject
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.inject](https://modernjs.dev/builder/api/config-html.html#htmlinject)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/inject.md';
+
+<Main />