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

package/en/configure/app/tools/style-loader.md

@@ -0,0 +1,13 @@
+---
+title: tools.styleLoader
+sidebar_label: styleLoader
+sidebar_position: 1
+---
+
+:::info BUILDER
+This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.styleLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-styleloader)。
+:::
+
+import Main from '@modern-js/builder-doc/en/config/tools/styleLoader.md'
+
+<Main />

package/en/configure/app/tools/styled-components.md

@@ -0,0 +1,13 @@
+---
+title: tools.styledComponents
+sidebar_label: styledComponents
+sidebar_position: 1
+---
+
+:::info BUILDER
+This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.styledComponents](https://modernjs.dev/builder/zh/api/config-tools.html#tools-styledcomponents)。
+:::
+
+import Main from '@modern-js/builder-doc/en/config/tools/styledComponents.md'
+
+<Main />

package/en/configure/app/tools/terser.md

@@ -0,0 +1,13 @@
+---
+title: tools.terser
+sidebar_label: terser
+sidebar_position: 1
+---
+
+:::info BUILDER
+This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.terser](https://modernjs.dev/builder/zh/api/config-tools.html#tools-terser)。
+:::
+
+import Main from '@modern-js/builder-doc/en/config/tools/terser.md'
+
+<Main />

package/en/configure/app/tools/ts-checker.md

@@ -0,0 +1,13 @@
+---
+title: tools.tsChecker
+sidebar_label: tsChecker
+sidebar_position: 1
+---
+
+:::info BUILDER
+This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.tsChecker](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tschecker)。
+:::
+
+import Main from '@modern-js/builder-doc/en/config/tools/tsChecker.md'
+
+<Main />

package/en/configure/app/tools/ts-loader.md

@@ -0,0 +1,13 @@
+---
+title: tools.tsLoader
+sidebar_label: tsLoader
+sidebar_position: 1
+---
+
+:::info BUILDER
+This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.tsLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tsloader)。
+:::
+
+import Main from '@modern-js/builder-doc/en/config/tools/tsLoader.md'
+
+<Main />

package/en/configure/app/tools/webpack-chain.md

@@ -0,0 +1,13 @@
+---
+title: tools.webpackChain
+sidebar_label: webpackChain
+sidebar_position: 1
+---
+
+:::info BUILDER
+This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.webpackChain](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpackchain)。
+:::
+
+import Main from '@modern-js/builder-doc/en/config/tools/webpackChain.md'
+
+<Main />

package/en/configure/app/tools/webpack.md

@@ -0,0 +1,13 @@
+---
+title: tools.webpack
+sidebar_label: webpack
+sidebar_position: 1
+---
+
+:::info BUILDER
+This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.webpack](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpack)。
+:::
+
+import Main from '@modern-js/builder-doc/en/config/tools/webpack.md'
+
+<Main />

package/en/tutorials/foundations/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "基础",
+  "position": 1,
+  "collapsed": false
+}

package/en/tutorials/foundations/basic.md

@@ -0,0 +1,8 @@
+---
+title: JavaScript & React
+sidebar_position: 2
+---
+
+:::note Todo
+Coming Soon...
+:::

package/en/tutorials/foundations/introduction.md

@@ -0,0 +1,43 @@
+---
+title: Modern.js Introduce
+sidebar_position: 1
+---
+
+Welcome to Modern.js tutorials!
+
+After reading this section, you will have an initial understanding of Modern.js and use Modern.js to create your first application.
+
+:::note Follow
+Join our Lark group to ask questions and learn about the latest news.
+:::
+
+## What is Modern.js
+
+**Modern.js** is a progressive modern web development framework based on React.
+
+The framework has a variety of built-in out-of-the-box tools, excellent build performance, zero-configuration rendering paradigm switching, and integrated API calls. Starting from three solutions (Application solutions, Module solutions, Monorepo solutions), it supports front-end research and development of a complete period.
+
+Modern.js is ByteDance's underlying front-end framework, which has directly or indirectly served thousands of applications, including middle and back-end, PC Web, H5 and other application scenarios. The framework covers a full life cycle, has a complete plugin system, and provides a high degree of customization capabilities. Support custom solutions exclusive to business lines through generator plugin, customize various functional extensions and business requirements, and help developers build applications faster.
+
+## Why Modern.js
+
+Modern.js can provide developers with the ultimate **Development Experience**，make the app better **User Experience**。
+
+In the process of developing React applications, developers often need to design implementations for certain functions, or use other libraries and frameworks to solve these problems。
+
+Modern.js support all the configuration and tools required by React applications, and have built-in **additional functions and optimizations**. Developers can use React to build the UI of the application, and then gradually adopt Modern.js functions to solve common application requirements, such as routing, data fetch, state management, etc.
+
+It mainly contains the following features:
+
+- 🪜 **Progressive**：Create projects with the most streamlined templates, gradually turn on plugin capabilities through generators, and customize solutions.
+- 🏠 **Integration**：The development is unique to the production environment Web Server, CSR and SSR are isomorphic development, and the function as the API service call.
+- 📦 **Out Of The Box**：Default TS support, built-in build core, ESLint, debugging tools, full functionality can be tested.
+- 🌏 **Ecology**：Self-developed state management, micro frontend, module packaging, Monorepo solution and other peripheral requirements.
+- 🕸 **Routing Modes**：Contains controlled routing, routing based on file conventions (nested routing), configurable routing, etc。
+- 🚀 **Independently Build Core**：Support a variety of packaging tools, deep optimization bundle.
+
+## Next
+
+If you are a front-end beginner, you may find these concepts a bit complicated. We provide some [JavaScript and React](/docs/tutorials/foundations/basic) learning materials, you can do some understanding of them first。
+
+If you are an experienced developer and want to know how to use Modern.js, you can try [Create your first app](/docs/tutorials/first-app/overview), or read [Guide](/docs/guides/overview).

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@modern-js/main-doc",
+  "description": "Shared documentation of modern.js framework",
+  "homepage": "https://modernjs.dev",
+  "bugs": "https://github.com/modern-js-dev/modern.js/issues",
+  "repository": "modern-js-dev/modern.js",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "framework",
+    "modern",
+    "modern.js"
+  ],
+  "version": "0.0.0-next-20221116121040",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@modern-js/builder-doc": "0.0.0-next-20221116121040"
+  },
+  "devDependencies": {
+    "@modern-js/builder-doc": "0.0.0-next-20221116121040",
+    "ts-node": "^10",
+    "fs-extra": "^10",
+    "@types/node": "^16",
+    "@types/fs-extra": "^9"
+  },
+  "scripts": {}
+}

package/scripts/gen-config.ts

@@ -0,0 +1,60 @@
+import path from 'path';
+import fs from 'fs-extra';
+
+const tip: Record<string, string> = {
+  zh: '该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考',
+  en: 'This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to',
+};
+
+const createMarkdown = (
+  summary: {
+    dirname: string;
+    name: string;
+  },
+  key: string,
+) => {
+  const { name, dirname } = summary;
+
+  return `---
+title: ${dirname}.${name}
+sidebar_label: ${name}
+sidebar_position: 1
+---
+
+:::info BUILDER
+${
+  tip[key]
+} [${dirname}.${name}](https://modernjs.dev/builder/zh/api/config-${dirname}.html#${dirname}-${name.toLowerCase()})。
+:::
+
+import Main from '@modern-js/builder-doc/${key}/config/${dirname}/${name}.md'
+
+<Main />
+`;
+};
+
+const hyphenateRE = /\B([A-Z]+)/g;
+const hyphenate = function (str: string) {
+  return str.replace(hyphenateRE, '-$1').toLowerCase();
+};
+
+const configPath = 'configure/app';
+
+export const gen = (
+  jsonMap: Record<string, { name: string; dirname: string }[]>,
+) => {
+  Object.keys(jsonMap).forEach(key => {
+    const cwd = process.cwd();
+    const baseDir = path.join(cwd, key, configPath);
+
+    const json = jsonMap[key as 'zh' | 'en'];
+    json.forEach(summary => {
+      const mdDir = path.join(baseDir, summary.dirname);
+      const mdPath = path.join(mdDir, `${hyphenate(summary.name)}.md`);
+      if (!fs.existsSync(mdDir)) {
+        fs.mkdirpSync(mdDir);
+      }
+      fs.writeFileSync(mdPath, createMarkdown(summary, key));
+    });
+  });
+};

package/scripts/sync.ts

@@ -0,0 +1,36 @@
+import fs from 'fs';
+import path, { basename, dirname, extname } from 'path';
+import { gen } from './gen-config';
+
+const walk = (dir: string) => {
+  const fl: string[] = [];
+  fs.readdirSync(dir).forEach(ff => {
+    const fpath = path.join(dir, ff);
+    if (fs.statSync(fpath).isDirectory()) {
+      fl.push(...walk(fpath));
+    } else if (extname(fpath) === '.md') {
+      fl.push(fpath);
+    }
+  });
+  return fl;
+};
+
+const summary = (lng: string) => {
+  const fl = walk(
+    path.join(
+      process.cwd(),
+      `./node_modules/@modern-js/builder-doc/${lng}/config`,
+    ),
+  );
+  return fl.map(fpath => {
+    return {
+      name: basename(fpath).replace(extname(fpath), ''),
+      dirname: basename(dirname(fpath)),
+    };
+  });
+};
+
+gen({
+  zh: summary('zh'),
+  en: summary('en'),
+});

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@modern-js/tsconfig/base",
+  "compilerOptions": {
+    "jsx": "preserve"
+  },
+  "include": ["./src", "./navbar.js", "./sidebar.js", "./scripts"]
+}

package/zh/apis/app/commands/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "命令",
+  "position": 3,
+  "link": {
+    "type": "doc",
+    "id": "apis/app/commands/index"
+  }
+}

package/zh/apis/app/commands/build.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 5
+---
+
+```bash
+Usage: modern build [options]
+
+build application
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help  显示命令帮助
+  --analyze   分析构建产物体积，查看各个模块打包后的大小
+```
+
+`modern build` 命令默认会在 `/dist` 目录下构建出可用于生产环境的产物。
+
+可以通过修改配置 [`output.distPath`](/docs/configure/app/output/dist-path) 指定产物的输出目录。
+
+## 分析构建产物体积
+
+执行 `npx modern build --analyze` 命令，可以在打包生产环境代码的同时，产出一个分析构建产物体积的 HTML 文件：
+
+```
+Bundle Analyzer saved report to /example/dist/report.html
+File sizes after production build:
+
+  122.35 KB  dist/static/js/885.1d4fbe5a.js
+  2.3 KB     dist/static/js/main.4b8e8d64.js
+  761 B      dist/static/js/runtime-main.edb7cf35.js
+  645 B      dist/static/css/main.0dd3ecc1.css
+```
+
+手动在浏览器中打开上述 HTML 文件，可以看到打包产物的瓦片图，并进行包体积分析和优化：
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
+
+> 该功能基于 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 实现。
+
+## 命令行参数
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />

package/zh/apis/app/commands/dev.md

@@ -0,0 +1,31 @@
+---
+sidebar_position: 1
+---
+
+# dev
+
+```bash
+Usage: modern dev [options]
+
+本地开发命令
+
+Options:
+  -e --entry <entry>    指定入口，编译特定的页面
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+  --analyze             分析构建产物体积，查看各个模块打包后的大小
+  --api-only            仅启动 API 接口服务
+```
+
+`modern dev` 命令启动一个开发服务器，同时监听源文件变化，默认支持 React Fast Refresh：
+
+```bash
+App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />

package/zh/apis/app/commands/index.md

@@ -0,0 +1,12 @@
+---
+type: ref
+---
+
+# 命令
+
+本节涵盖了使用应用工程的所有命令。
+
+
+
+
+

package/zh/apis/app/commands/inspect.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 7
+---
+
+```
+Usage: modern inspect [options]
+
+inspect internal webpack config
+
+Options:
+  --env <env>           查看指定环境下的配置 (default: "development")
+  --output <output>     指定在 dist 目录下输出的路径 (default: "/")
+  --no-console          不在终端中输出完整结果
+  --verbose             在结果中展示函数的完整内容
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+```
+
+`modern inspect` 命令，用于查看项目的 webpack 完整配置。
+
+在项目根目录下执行命令 `npx modern inspect`，会将 webpack 配置输出在终端界面，同时也会在项目的 `dist` 目录生成一份 `webpack.client.inspect.js` 文件，开发者可手动打开查看。
+
+## 指定环境
+
+默认情况下，会输出开发环境的 webpack 配置，可以使用 `env` 选项来输出生产环境的配置：
+
+```bash
+modern inspect --env production
+```
+
+## 配置类型
+
+### SSR 配置
+
+如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.ssr.inspect.js` 文件，对应 SSR 构建时的 webpack 配置。
+
+### Modern 配置
+
+如果项目开启了 [enableModernMode](/docs/configure/app/output/enable-modern-mode) 选项，则在 `dist` 目录会另外生成一份 `webpack.modern.inspect.js` 文件，对应现代浏览器的 webpack 配置。

package/zh/apis/app/commands/lint.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 4
+title: lint
+---
+
+```bash
+Usage: modern lint [options] [...files]
+
+lint and fix source files
+
+Options:
+  --no-fix    disable auto fix source file
+  -h, --help  display help for command
+```
+
+运行 `ESLint` 检查代码语法情况， 通长情况下，我们只需要在 `git commit` 阶段通过 `lint-staged` 检查本次提交修改的部分代码。
+
+* `--no-fix` 参数设置后可以关闭自动修复 lint 错误代码的能力。
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />

package/zh/apis/app/commands/new.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 2
+---
+
+```bash
+Usage: modern new [options]
+
+应用工程中执行生成器
+
+Options:
+  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
+  -c, --config <config>  生成器运行默认配置(JSON 字符串)
+  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
+  --registry             生成器运行过程中定制 npm Registry
+  -h, --help             显示命令帮助
+```
+
+`modern new` 命令用于在已有项目中添加项目元素。
+
+比如添加应用入口、启用启用一些可选功能如 Tailwind CSS、微前端开发模式等。
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />
+
+### 添加入口
+
+在应用工程中，执行 `new` 命令添加入口如下：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「应用入口」
+? 请填写入口名称 entry
+? 是否需要调整默认配置? 否
+```
+
+### 启用启用可选功能
+
+在应用工程中，执行 `new` 命令启用可选能力如下：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 (Use arrow keys)
+❯ 启用 Tailwind CSS 支持
+  启用 Less 支持
+  启用 Sass 支持
+  启用「BFF」功能
+  启用「微前端」模式
+  启用「单元测试 / 集成测试」功能
+  启用「Visual Testing (Storybook)」模式
+```
+
+:::caution 注意
+`--config` 参数对应参数值需要使用 JSON 字符串。
+
+pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
+:::

package/zh/apis/app/commands/start.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 6
+---
+
+```bash
+Usage: modern start [options]
+
+start server
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+  --api-only            仅启动 API 接口服务
+```
+
+通常使用 `modern start` 命令在生产环境下启用应用工程, 需要提前执行 [`build`](/docs/apis/app/commands/build) 命令构建出对应产物。
+
+默认情况下，应用将会在 `localhost:8080` 启动，可以通过 `server.port` 修改 Server 端口号：
+
+```js
+export default defineConfig({
+  server: {
+    port: 8081,
+  }
+})
+```
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />
+
+

package/zh/apis/app/commands/test.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 3
+---
+
+```bash
+Usage: modern test [options]
+
+Options:
+  -h, --help  显示命令帮助
+```
+
+:::caution 注意
+`modern test` 命令需要先通过 [`new`](/docs/apis/app/commands/new) 命令启用「单元测试 / 集成测试」功能
+:::
+
+`modern test` 命令会自动运行项目下的测试用例，效果如下：
+
+```bash
+$ npx modern test
+ PASS  src/tests/index.test.ts
+  The add method
+    ✓ should work fine. (2ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
+Snapshots:   0 total
+Time:        0.994 s, estimated 1 s
+```
+
+:::info 注
+`src` 和 `api` 目录下面 `*.test.(js|ts)` 都会默认识别为测试用例。
+:::
+
+import CommandTip from '@site/docs/components/command-tip.md'
+
+<CommandTip />

package/zh/apis/app/commands/upgrade.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 8
+---
+
+```
+Usage: modern upgrade [options]
+
+升级 Modern.js 到最新版本
+
+Options:
+  --registry <registry>  定制 npm registry (default: "")
+  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
+  --cwd <cwd>            项目路径 (default: "")
+  -h, --help             display help for command
+```
+
+`modern upgrade` 命令，用于升级项目 Modern.js 相关依赖至最新版本。
+
+在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。
+
+:::info
+命令在 `@modern-js/app-tools` 版本 >= 1.17.0 提供，之前版本可使用 `npx @modern-js/upgrade` 进行升级。
+:::

package/zh/apis/app/hooks/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "文件约定",
+  "position": 1,
+  "link": {
+    "type": "doc",
+    "id": "apis/app/hooks/index"
+  }
+}

package/zh/apis/app/hooks/api/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "api/",
+  "position": 2
+}

package/zh/apis/app/hooks/api/framework/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "框架写法",
+  "position": 2
+}