diff --git a/docs/tutorials/2-start.md b/docs/tutorials/2-start.md index 5790803c9..607e73ac7 100644 --- a/docs/tutorials/2-start.md +++ b/docs/tutorials/2-start.md @@ -240,7 +240,7 @@ export default defineConfig({ // ... }); ``` -When building for production, the injected resources url would be `https://cdn.com/index-s2f3.s14dqwa.js`. For example, in your output html, all ` + + +``` + +当加载动态脚本和CSS时，动态获取的资源url也将是：`https://cdn.com/` + + ## 配置 Alias 以及 Externals Alias 和 externals 是最常用的配置之一, 在 Farm 中，可以使用 `compilation.resolve.alias` 和 `compilation.externals` 配置项: @@ -225,11 +283,7 @@ export default defineConfig({ ### 常用配置 配置示例： ```ts -import type { UserConfig } from '@farmfe/core'; - -function defineConfig(config: UserConfig) { - return config; -} +import { defineConfig } from '@farmfe/core'; export default defineConfig({ // 所有开发服务器选项都在 server 下 @@ -249,7 +303,7 @@ export default defineConfig({ ``` 对于上面的示例，我们使用了以下选项： * **打开**：自动打开指定端口的浏览器 -* **端口**：将开发服务器端口设置为“9001” +* **端口**：将开发服务器端口设置为`9001` * **hmr**：设置 hmr 端口和监视文件，我们忽略 `auto_generate` 目录下的文件更改。 @@ -257,11 +311,7 @@ export default defineConfig({ 配置服务器代理。 基于[koa-proxies](https://www.npmjs.com/package/koa-proxies)实现，具体选项参考其文档，示例： ```ts -import type { UserConfig } from '@farmfe/core'; - -function defineConfig(config: UserConfig) { - return config; -} +import { defineConfig } from '@farmfe/core'; export default defineConfig({ server: { @@ -274,5 +324,21 @@ export default defineConfig({ }, }, }); +``` + +## 配置 root 和 envDir +使用`root`和`envDir`指定项目根目录和加载环境变量的目录。 在`farm.config.ts`中添加以下选项： -``` \ No newline at end of file +```ts title="farm.config.ts" +import path from 'node:path'; +import { defineConfig } from '@farmfe/core'; + +export default defineConfig({ + root: path.join(process.cwd(), 'client'), + envDir: 'my-env-dir' +}); +``` + +:::note +有关 `envDir` 的详细信息，请参阅[环境变量和模式](/docs/features/env) +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/3-build.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/3-build.md index d237a8a73..278ea0dcf 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/3-build.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/3-build.md @@ -1,30 +1,130 @@ # 3. 使用 Farm 构建生产项目 -默认情况下，Farm 已经为生产构建开启了以下功能的支持： -* **`Tree Shake`**：裁剪和过滤无关模块和代码 -* **`压缩`**：对产物进行压缩和混淆，减少产物体积 -* **`自动注入 Polyfill`**：Farm 默认对项目降级到 ES5，这意味着 Farm 构建的产物几乎可以在所有浏览器上运行 -* **`自动进行局部打包`**: 依据依赖关系以及大小，将项目进行局部打包，对于每次资源请求，生成 25 个左右的资源，在保证并行加载性能的同时，尽可能提升缓存命中率 - -## 添加 build script -在 `package.json` 中添加 build script: -```json title="package.json" {7} +默认情况下，Farm 已启用对生产版本的以下功能的支持： +* **`Tree Shake`**：裁剪和过滤不相关的模块和代码 +* **`压缩`**：压缩并破坏输出资源。 +* **`自动注入Polyfill`**：默认情况下Farm降级到现代浏览器(ES7)，如果需要旧版浏览器支持，请配置[`targetEnv`](/docs/config/compilation-options#output-targetenv) +* **`自动局部打包`**：根据依赖关系和大小，对项目进行部分打包。 对于每个资源请求，会生成大约25个资源，以保证并行加载性能，并尽可能提高缓存命中率。 + +## 配置输出目录 +在 `package.json` 中添加构建脚本： + +```json title="package.json" {7-8} { - "name": "1-create-a-project", - "version": "1.0.0", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1", - "start": "farm start", - "build": "farm build" - }, - // ... ignore other fields + "name": "1-create-a-project", + "version": "1.0.0", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "farm start", + "build": "farm build", + "preview": "farm preview" + }, + // ...ignore other fields } ``` -然后执行 `npm run build` 即可。 -## 配置 Tree Shake 和压缩 -## Configure Tree Shake and compression -* [Tree Shake](/docs/features/tree-shake) -* [Minification](/docs/features/minification) +然后执行`npm run build`，构建的资源将被生成到`build`目录 + +```text +build +├─ favicon.ico +├─ index.html +├─ index_02bc.bd68e90b.js +├─ index_02bc.bd68e90b.js.map +├─ index_1c74.4b50f73e.js +├─ index_7734.440d56a3.js +├─ index_880b.4631ecee.js +├─ index_8d49.63f7b906.css +├─ index_8d49.63f7b906.css.map +├─ index_9025.84e1f8e6.js +├─ index_ca37.f2c276ef.js +├─ index_ef2f.e25349d8.js +├─ index_f346.369a7312.js +``` + +如果您想自定义资源生成的路径，您可以使用： +* [`output.filename`](/docs/config/compilation-options#outputfilename) +* [`output.assetsFilename`](/docs/config/compilation-options#outputassetsfilename) + +```ts +import defineConfig from '@farmfe/core'; + +export default defineConfig({ + compilation: { + output: { + path: 'build', + filename: 'assets/[name].[hash].[ext]', + assetsFilename: 'static/[resourceName].[ext]' + } + } +}) +``` + +对于上面的示例，所有`js/css`将被发送到`build/assets/`（例如：`build/assets/index-ea54.abbe3e.js`）。 所有静态资源（例如图像）都将发送到`build/static`（例如：`build/static/background.png`） + +## 预览构建的资源 +资源构建完成后，您可以通过`npm run Preview`进行预览： + +```sh +$ npm run preview + +> 3-build@1.0.0 preview +> farm preview + +[ Farm ] Using config file at /root/tutorials/3-build-for-production/farm.config.ts +[ Farm ] preview server running at: + +[ Farm ] > Local: http://localhost:1911/ +[ Farm ] > Network: http://198.18.0.1:1911/ +[ Farm ] > Network: http://10.242.197.146:1911/ +[ Farm ] > Network: http://192.168.1.31:1911/ +``` + +打开`http://localhost:1911/`来预览项目。 + +## 浏览器兼容性 +默认情况下，Farm 将项目构建到本机支持`async/await`的现代浏览器： + +* Chrome >= 62 +* Firefox >= 63 +* Safari >= 13.1 +* Edge >= 79 + +可以使用 [output.targetEnv](/docs/config/compilation-options#output-targetenv) 来配置目标浏览器： + +```ts +import { defineConfig } from '@farmfe/core'; + +export default defineConfig({ + compilation: { + output: { + targetEnv: 'browser-legacy' + } + } +}) +``` + +在上面的例子中，Farm 会将语法降级为 `es5` 并自动注入 polyfill。 然后我们必须安装`core-js@3`来进行`polyfill`注入： + +```sh +pnpm add -D core-js@3 +``` + +:::note +* 如果您的目标是旧版浏览器，则需要手动安装 `core-js@3`。 +* 如果你想更精确地配置浏览器目标，请参阅[语法 Downgrade 和 Polyfill](/docs/advanced/polyfill) +::: + +## 配置 Tree Shake 和 Minify +出于性能原因，像`treeShake`和`minify`这样的生产优化在`development`中默认被`禁用`，而在`生产`中默认被`启用`。 但如果手动配置了`treeShake`或`minify`，则无论`development`或`productive`都将使用默认值。 + +有关 Tree Shake 和 Minify 的详细信息，请参阅： +* [Tree Shake](/docs/advanced/tree-shake) +* [Minification](/docs/advanced/minification) + ## 配置局部打包策略 -* [Partial Bundling](/docs/features/partial-bundling) \ No newline at end of file +:::note +详细信息参考[局部打包](/docs/advanced/partial-bundling)。 +::: + +Farm 已经启用了打包的最佳实践，请确保您确实需要手动配置打包策略，参考[局部打包](/docs/advanced/partial-bundling) 了解详情。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/why-farm.md b/i18n/zh/docusaurus-plugin-content-docs/current/why-farm.md index 3452ae0d8..a612a7eec 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/why-farm.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/why-farm.md @@ -4,6 +4,10 @@ sidebar_position: 2 # 为什么需要 Farm？ +## Farm 是什么？ +Farm 是一个非常快的基于 Rust 的 Web 构建工具，类似 `webpack` 和 `vite`，但**更快**。 farm `resolve, load, transform` 所有 `asset(js/jsx/ts/tsx、css/sass/less、html、静态资源、json 等)`，并将它们打包成一系列`可部署文件`。 Farm 是一个速度极快的构建工具，可帮助您构建更快的 `web/nodejs` 应用程序。 + +## 为什么需要 Farm？ 随着 web 项目规模的扩大，构建性能已经成为主要瓶颈，对于一个庞大的项目，使用 webpack 编译可能需要 10min 甚至更多，一次 hmr 更新可能需要 10s 甚至更多，严重降低了研发效率。 因此我们急需极速的构建工具，解决项目编译性能问题。然后 vite/snowpack 这样的 unbundled 工具应运而生，此类工具主要有下面三个特性： @@ -17,11 +21,11 @@ sidebar_position: 2 * **拆包优化困难**： 受限于 Rollup，拆包配置不够灵活、易用。 * 而 Vite 在 dev 上之所以这么快，esbuild 功不可没，它是用 go 编写的。 Go 利用了原生平台的优势，远快于 Js。 -事实上，我们真正需要的是一个快速、强大、一致的 Web 构建工具，可以在解决上述问题的基础上，提供更加极致的编译效率。因此我们开发了 Farm。 +事实上，我们真正需要的是一个快速、强大、一致的 Web 构建工具，可以在解决上述问题的基础上，提供更加极致的编译效率。因此我们设计并开发了 Farm。 -:::note +