docs: add more guide docs (umijs/father-next#68)

* docs: add more guide docs

* docs: typo & link

* docs: use same text

* Update docs/guide/pre-bundle.md

Co-authored-by: wangxingkang <wang_xingkang@qq.com>

* docs: add migrade guide

* docs: update readme

Co-authored-by: wangxingkang <wang_xingkang@qq.com>

README.md

@@ -1,5 +1,22 @@
 # father
 
-[![version](https://badgen.net/npm/v/father/next)](https://www.npmjs.com/package/father) [![codecov](https://codecov.io/gh/umijs/father-next/branch/master/graph/badge.svg)](https://codecov.io/gh/umijs/father-next) [![GitHub Actions status](https://github.com/umijs/father-next/workflows/CI/badge.svg)](https://github.com/umijs/father-next)
+[![version](https://badgen.net/npm/v/father)](https://www.npmjs.com/package/father) [![codecov](https://codecov.io/gh/umijs/father/branch/master/graph/badge.svg)](https://codecov.io/gh/umijs/father) [![GitHub Actions status](https://github.com/umijs/father/workflows/CI/badge.svg)](https://github.com/umijs/father)
 
-Now father@4 RC version is available, you can try it with our docs: [中文](./docs/guide.md)
+father 是一款 NPM 包研发工具，能够帮助开发者更高效、高质量地研发 NPM 包、生成构建产物、再完成发布。它主要具备以下特性：
+
+- ⚔️ **双模式构建：** 支持 Bundless 及 Bundle 两种构建模式，ESModule 及 CommonJS 产物使用 Bundless 模式，UMD 产物使用 Bundle 模式
+- 🎛 **多构建核心：** Bundle 模式使用 Webpack 作为构建核心，Bundless 模式使用 esbuild 及 Babel 两种构建核心，可通过配置自由切换
+- 🔖 **类型生成：** 无论是源码构建还是依赖预打包，都支持为 TypeScript 模块生成 `.d.ts` 类型定义
+- 🩺 **项目体检：** 对 NPM 包研发常见误区做检查，让每一次发布都更加稳健
+- 🏗 **微生成器：** 为项目追加生成常见的工程化能力，例如使用 jest 编写测试
+- 📦 **依赖预打包：** 开箱即用的依赖预打包能力，帮助 Node.js 框架/库提升稳定性、不受上游依赖更新影响（实验性）
+
+访问 [指南](./docs/guide/index.md) 及 [配置项](./docs/config.md) 了解更多。
+
+## 贡献指南
+
+查看 [CONTRIBUTING](./CONTRIBUTING.md) 文档。
+
+## License
+
+[MIT](./LICENSE)

docs/guide.md

@@ -0,0 +1 @@
+./guide/index.md

docs/guide/build-mode.md

@@ -0,0 +1,90 @@
+# 构建模式
+
+## Bundless
+
+Bundless 即文件到文件的构建模式，它不对依赖做任何处理，只对源码做平行编译输出。目前社区里的 [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html)、[unbuild](https://github.com/unjs/unbuild) 及旧版 father 的 babel 模式都是对源码做 Bundless 构建的构建工具。
+
+在 father 4 中，输出 ESModule 产物和 CommonJS 产物时都会采用 Bundless 构建模式，来看一下 father 的 Bundless 构建模式会如何工作。
+
+假定有这样的源码结构：
+
+```bash
+.
+└── src
+    ├── index.less
+    ├── index.tsx
+    └── util.js
+```
+
+配合以下构建配置：
+
+```js
+export default {
+  esm: { output: 'dist' },
+  // 或者
+  cjs: { output: 'dist' },
+};
+```
+
+则会被 father 输出为：
+
+```bash
+.
+└── dist
+    ├── index.d.ts
+    ├── index.js
+    ├── index.less
+    └── util.js
+```
+
+可以发现，在 Bundless 模式下，father 对源码的处理逻辑如下：
+
+1. TypeScript 模块会被编译为 JavaScript 模块，并且输出对应的 `.d.ts` 类型文件
+2. JavaScript 模块会被编译为 JavaScript 模块，做兼容性处理
+3. 其他模块会被直接拷贝输出，不做编译
+
+### 如何选择
+
+Bundless 模式下的产物可以被项目选择性引入，同时也具备更好的可调试性。对于大部分项目而言，Bundless 应该都是最好的选择，这也是社区大部分项目的选择。
+
+关于如何选择 ESModule 产物和 CommonJS 产物，可参考 [构建 ESModule 和 CommonJS 产物](./esm-cjs.md#如何选择) 文档。
+
+## Bundle
+
+Bundle 即将源码打包的构建模式，它以入口文件作为起点、递归处理全部的依赖，然后将它们合并输出成构建产物。目前社区里的 [Webpack](https://webpack.js.org)、[Rollup](https://rollupjs.org/guide/en/) 及旧版 father 的 rollup 模式都是对源码做 Bundle 构建的构建工具。
+
+在 father 4 中，仅输出 UMD 产物时会使用 Bundle 构建模式。来看一下 father 的 Bundle 构建模式会如何工作。
+
+假定有这样的源码结构：
+
+```bash
+.
+└── src
+    ├── index.less
+    └── index.tsx # 源码中引入 index.less
+```
+
+配合以下构建配置：
+
+```ts
+export default {
+  umd: { output: 'dist' },
+};
+```
+
+则会被 father 输出为：
+
+```bash
+.
+└── dist
+    ├── index.min.js
+    └── index.min.css
+```
+
+可以发现，在 Bundless 模式下，father 会对源码进行打包，最后输出压缩后的 JavaScript 产物和 CSS 产物。
+
+### 如何选择
+
+Bundle 的产物具备更好的一体性。father 中只有 UMD 产物是 Bundle 构建模式，所以在需要 UMD 产物时就随之选择了 Bundle 构建模式。
+
+关于何时选择 UMD 产物，可参考 [构建 UMD 产物](./umd.md#如何选择) 文档。

docs/guide/dev.md

@@ -0,0 +1,27 @@
+# 开发
+
+将构建配置设置完毕后，即可开始开发。
+
+## 实时编译产物
+
+开发过程中我们需要实时编译产物，以便进行调试、验证：
+
+```bash
+# 执行 dev 命令，开启实时编译
+$ father dev
+```
+
+一旦源码或配置文件发生变化，产物将会实时增量编译到输出目录。
+
+> 注：目前仅 Bundless 模式支持实时编译
+
+## 在项目中调试
+
+在测试项目中，使用 `npm link` 命令将该项目链接到测试项目中进行调试、验证：
+
+```bash
+$ cd test-project
+$ npm link /path/to/your-father-project .
+```
+
+开发、验证完成后，即可 [发布](./release.md) 该 NPM 包。

docs/guide/doctor.md

@@ -0,0 +1,65 @@
+# 项目体检
+
+father 的项目体检能力可以帮助我们发现项目的潜在问题，并提供改进建议，只需执行：
+
+```bash
+$ father doctor
+```
+
+目前包含如下规则。
+
+## PACK_FILES_MISSING
+
+- 级别：错误 ❌
+- 说明：
+
+有配置 files 字段但却不包含构建产物目录，这会导致发布后的 NPM 包找不到对应的模块。
+
+## EFFECTS_IN_SIDE_EFFECTS
+
+- 级别：错误 ❌
+- 说明：
+
+`package.json` 文件中的 `sideEffects` 字段配置有误，例如：
+
+1. 构建产物里有引入样式文件，却将 `sideEffects` 配置为 `false`，这会导致实际项目编译后丢失样式
+2. 使用了 Rollup.js 不兼容的通配方式 `*.css`，这在 Webpack 项目中意味着匹配全部的 CSS，但在 Rollup.js 项目中意味着顶层的 CSS
+
+## PHANTOM_DEPS
+
+- 级别：错误 ❌
+- 说明：
+
+源码中使用了某个依赖，但却没有声明在 `dependencies` 中，这会导致项目引用到[幽灵依赖](https://rushjs.io/pages/advanced/phantom_deps/)，它可能不存在，也可能是错误的版本，使得项目存在运行失败的风险。
+
+## PREFER_PACK_FILES
+
+- 级别：警告 ⚠️
+- 说明：
+
+建议使用 `files` 字段声明要发布到 NPM 的文件，以减小 NPM 包安装体积。
+
+## PREFER_NO_CSS_MODULES
+
+- 级别：警告 ⚠️
+- 说明：
+
+不建议使用 CSS Modules，用户难以覆写样式，且会给用户项目增加额外的编译成本
+
+## PREFER_BABEL_RUNTIME
+
+- 级别：警告 ⚠️
+- 说明：
+
+建议安装 `@babel/runtme` 到 `dependencies`，以节省构建产物大小。
+
+> 注：该规则仅在 `transformer` 是 `babel` 且 `platform` 是 `browser` 时生效
+
+## DUP_IN_PEER_DEPS
+
+- 级别：警告 ⚠️
+- 说明：
+
+`peerDependencies` 和 `dependencies` 里有相同依赖，建议根据项目实际需要去掉其中一个。
+
+如果你有其他的 NPM 包的研发建议，欢迎评论到 [issue](https://github.com/umijs/father-next/issues/36) 中，规则讨论通过后将会被添加。

docs/guide/esm-cjs.md

@@ -0,0 +1,44 @@
+# 构建 ESModule 与 CommonJS 产物
+
+> 在 father 项目中，ESModule 产物构建与 CommonJS 产物构建类似，所以本章做合并介绍。
+
+## 如何选择
+
+ESModule 是 JavaScript 使用的模块规范，而 CommonJS 是 Node.js 使用的模块规范，这我们已经很熟悉了，所以我们的项目需要输出什么产物，只需要根据使用情况判断即可：
+
+| 产物类型/运行环境 | Browser | Node.js  | Both    |
+| ----------------- | ------- | -------- | ------- |
+| ESModule          | ✅ 推荐 | 暂不推荐 | ✅ 推荐 |
+| CommonJS          | 没必要  | ✅ 推荐  | ✅ 推荐 |
+
+额外说明：
+
+1. 由于 Node.js 社区的 Pure ESM 推进[仍有阻碍](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)，所以为了通用性考虑，目前仍然建议大家为 Node.js 项目产出 CommonJS 产物，未来 father 也会推出同时产出 ESModule 产物的兼容方案，敬请期待
+2. 对于 Browser 运行环境，CommonJS 产物是没必要的，无论哪种模块构建工具都能帮我们解析，加上 Vite 这类使用原生 ESModule 产物的构建工具已经成熟，使用 ESModule 才是面向未来的最佳选择
+3. Both 是指构建产物要同时用于 Browser 和 Node.js 的项目，比如 react-dom、umi 等
+
+## 如何构建
+
+只需要使用 `esm` 及 `cjs` 配置项，再执行 `father build` 即可产出 ESModule 和 CommonJS 产物：
+
+```js
+// .fatherrc.js
+export default {
+  // 以下为 esm 配置项启用时的默认值，有自定义需求时才需配置
+  esm: {
+    input: 'src', // 默认编译目录
+    target: 'browser', // 默认构建为 Browser 环境的产物
+    transformer: 'babel', // 默认使用 babel 以提供更好的兼容性
+  },
+  // 以下为 cjs 配置项启用时的默认值，有自定义需求时才需配置
+  cjs: {
+    input: 'src', // 默认编译目录
+    target: 'node', // 默认构建为 Node.js 环境的产物
+    transformer: 'esbuild', // 默认使用 esbuild 以获得更快的构建速度
+  },
+};
+```
+
+更多配置项可参考 [配置项](../config.md)。
+
+在 father 项目中，ESModule 产物及 CommonJS 产物都以 Bundless 模式进行构建，关于 Bundless 模式的介绍可参考 [构建模式 - Bundless](./build-mode.md#bundless)。

docs/guide/index.md

@@ -0,0 +1,46 @@
+# 指南
+
+## 介绍
+
+father 是一款 NPM 包研发工具，能够帮助开发者更高效、高质量地研发 NPM 包、生成构建产物、再完成发布。它主要具备以下特性：
+
+- ⚔️ **双模式构建：** 支持 Bundless 及 Bundle 两种构建模式，ESModule 及 CommonJS 产物使用 Bundless 模式，UMD 产物使用 Bundle 模式
+- 🎛 **多构建核心：** Bundle 模式使用 Webpack 作为构建核心，Bundless 模式使用 esbuild 及 Babel 两种构建核心，可通过配置自由切换
+- 🔖 **类型生成：** 无论是源码构建还是依赖预打包，都支持为 TypeScript 模块生成 `.d.ts` 类型定义
+- 🩺 **项目体检：** 对 NPM 包研发常见误区做检查，让每一次发布都更加稳健
+- 🏗 **微生成器：** 为项目追加生成常见的工程化能力，例如使用 jest 编写测试
+- 📦 **依赖预打包：** 开箱即用的依赖预打包能力，帮助 Node.js 框架/库提升稳定性、不受上游依赖更新影响（实验性）
+
+## 兼容性
+
+father 本身需要在 Node.js v14 以上的环境中运行，使用前请确保已安装 Node.js v14 及以上版本。
+
+father 产出的 Node.js 产物默认兼容到 Node.js v14，Browser 产物默认兼容到 ES5（IE11），暂不支持修改。
+
+## 快速上手
+
+通过 `create-father` 快速创建一个 father 项目：
+
+```bash
+$ npx create-father my-father-project
+```
+
+> 脚手架中仅包含最基础的配置，更多配置项及作用可以参考 [配置项文档](./config.md)。
+
+执行构建：
+
+```bash
+$ npx father build
+```
+
+查看 `dist` 文件夹，可以看到构建产物已被生成出来。恭喜你，已经完成了第一个 father 项目的构建工作 🎉
+
+接下来，你可以查看其它文档了解 father 的更多功能：
+
+- [Bundless 与 Bundle 构建模式](./build-mode.md)
+- [构建 ESModule 和 CommonJS 产物](./esm-cjs.md)
+- [构建 UMD 产物](./umd.md)
+- [依赖预打包](./pre-bundle.md)
+- [执行项目体检](./doctor.md)
+- [开发指南](./dev.md)
+- [发布指南](./release.md)