From 204b8168da353bb97eac6611ecb0719512baf53e Mon Sep 17 00:00:00 2001 From: ADNY <66500121+ErKeLost@users.noreply.github.com> Date: Mon, 15 Jan 2024 15:51:35 +0800 Subject: [PATCH] chore: update farm api docs (#50) * chore: update farm api docs * chore: update ai generate * chore: update ai generate * chore: update ai generate * chore: update AI * chore: update plugin siderBar * chore: update theme * chore: update md * chore: update md * chore: update md * chore: update md --- .vscode/settings.json | 1 + docs/api/hmr-api.md | 1 + docs/api/javascript-api.md | 1 + docs/api/js-plugin-api.md | 1 + docs/api/rust-api.md | 1 + docs/api/rust-plugin-api.md | 1 + docs/benchmark.md | 67 +++++-- docs/cli/build.md | 0 docs/cli/cli-api.md | 172 ++++++++++++++++++ docs/cli/preview.md | 0 docs/cli/start.md | 0 docs/cli/watch.md | 0 docs/config/compilation-options.md | 13 +- docs/config/dev-server.md | 8 +- docs/features/html.md | 72 ++++---- docs/plugins/writing-plugins/js-plugin.md | 43 +++-- docs/quick-start.mdx | 9 +- docusaurus.config.js | 4 +- i18n/zh/code.json | 21 ++- .../current/api/hmr-api.md | 1 + .../current/api/javascript-api.md | 1 + .../current/api/js-plugin-api.md | 1 + .../current/api/rust-api.md | 1 + .../current/api/rust-plugin-api.md | 1 + .../current/cli/cli-api.md | 172 ++++++++++++++++++ .../current/config/compilation-options.md | 16 +- .../current/config/plugins-options.md | 13 +- .../current/features/html.md | 69 +++---- .../plugins/writing-plugins/js-plugin.md | 2 +- .../current/quick-start.mdx | 6 +- package.json | 1 + pnpm-lock.yaml | 13 ++ sidebars.js | 14 +- src/css/_admonition.scss | 18 +- 34 files changed, 579 insertions(+), 165 deletions(-) create mode 100644 docs/api/hmr-api.md create mode 100644 docs/api/javascript-api.md create mode 100644 docs/api/js-plugin-api.md create mode 100644 docs/api/rust-api.md create mode 100644 docs/api/rust-plugin-api.md delete mode 100644 docs/cli/build.md create mode 100644 docs/cli/cli-api.md delete mode 100644 docs/cli/preview.md delete mode 100644 docs/cli/start.md delete mode 100644 docs/cli/watch.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/api/hmr-api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/api/javascript-api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/api/js-plugin-api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/api/rust-api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/api/rust-plugin-api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cli/cli-api.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 9d9b13307..26de816c5 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -16,6 +16,7 @@ "PUFY", "raxjs", "Rspack", + "shikiji", "shulandmimi", "tailwindcss", "Turbopack" diff --git a/docs/api/hmr-api.md b/docs/api/hmr-api.md new file mode 100644 index 000000000..f92888fe3 --- /dev/null +++ b/docs/api/hmr-api.md @@ -0,0 +1 @@ +# Hmr Api diff --git a/docs/api/javascript-api.md b/docs/api/javascript-api.md new file mode 100644 index 000000000..d1daa55bc --- /dev/null +++ b/docs/api/javascript-api.md @@ -0,0 +1 @@ +# JavaScript Api diff --git a/docs/api/js-plugin-api.md b/docs/api/js-plugin-api.md new file mode 100644 index 000000000..8e03502ca --- /dev/null +++ b/docs/api/js-plugin-api.md @@ -0,0 +1 @@ +# Js Plugin Api diff --git a/docs/api/rust-api.md b/docs/api/rust-api.md new file mode 100644 index 000000000..91a278a54 --- /dev/null +++ b/docs/api/rust-api.md @@ -0,0 +1 @@ +# Rust Api diff --git a/docs/api/rust-plugin-api.md b/docs/api/rust-plugin-api.md new file mode 100644 index 000000000..da099bbc0 --- /dev/null +++ b/docs/api/rust-plugin-api.md @@ -0,0 +1 @@ +# Rust Plugin Api diff --git a/docs/benchmark.md b/docs/benchmark.md index e762ae4a8..566b7d545 100644 --- a/docs/benchmark.md +++ b/docs/benchmark.md @@ -1,33 +1,70 @@ # Benchmarks +## Introduction + Using Turbopack's bench cases (1000 React components), see https://turbo.build/pack/docs/benchmarks. +### Run this benchmark yourself + > Test Repo：https://github.com/farm-fe/performance-compare > > Test Machine（Linux Mint 21.1 Cinnamon， 11th Gen Intel© Core™ i5-11400 @ 2.60GHz × 6， 15.5 GiB） +```ts +# Install dependencies +pnpm install + +# run benchmark +pnpm benchmark +``` + +### Data + +| | **Startup** | **HMR (Root)** | **HMR (Leaf)** | **Production Build** | +| ------- | ----------- | -------------- | -------------- | -------------------- | +| Webpack | 8035ms | 345ms | 265ms | 11321ms | +| Vite | 3078ms | 35ms | 18ms | 2266ms | +| Rspack | 831ms | 104ms | 96ms | 724ms | +| Farm | 403ms | 11ms | 10ms | 288ms | + --- -| | **Startup** | **HMR (Root)** | **HMR (Leaf)** | **Production Build** | -| --------- | ----------- | -------------- | -------------- | -------------------- | -| Webpack | 8035ms | 345ms | 265ms | 11321ms | -| Vite | 3078ms | 35ms | 18ms | 2266ms | -| Turbopack | 3731ms | 62ms | 54ms | 6442ms | -| Rspack | 831ms | 104ms | 96ms | 724ms | -| Farm | 403ms | 11ms | 10ms | 288ms | +## metrics + +- Cold StartUp Time: The time it takes to develop a build without caching + +- Hot StartUp Time: The time it takes to develop a build with caching + +- Cold Production Build Time: The time it takes to build a production build without caching + +- Hot Production Build Time: The time it takes to build a production build with caching + +- HMR Time: The time it takes to apply an update to a file and send it to the development server to the response + + - HMR Root: The time for updating a react component file that has no dependency + + - HMR Leaf: The time for updating a root react component, normally it is named `App.tsx` or `index.tsx` + +### Benchmark for all metrics + + + + + +### Benchmark of HMR -### Full Benchmark + -![performance](/img/20231204223204.png) + -### HMR Benchmark +### Benchmark of Startup -![performance](/img/hmr-linux.png) + -### Startup Benchmark + -![performance](/img/startup-linux.png) +### Benchmark of Production Build -### Production Build Benchmark + -![performance](/img/build-linux.png) + diff --git a/docs/cli/build.md b/docs/cli/build.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/cli/cli-api.md b/docs/cli/cli-api.md new file mode 100644 index 000000000..5552492c6 --- /dev/null +++ b/docs/cli/cli-api.md @@ -0,0 +1,172 @@ +# Farm CLI API + +The Farm CLI allows you to start, build, preview, and watch your application. + +To get a list of cli available to Farm, run the following command inside your command + +```json title="Terminal" +npx farm -h +``` + +The output look like this: + +```json title="Terminal" +farm/0.5.11 + +Usage: + $ farm [root] + +Commands: + [root] Compile the project in dev mode and serve it with farm dev server + build compile the project in production mode + watch watch file change + preview compile the project in watch mode + clean [path] Clean up the cache built incrementally + plugin [command] Commands for manage plugins + +For more info, run any command with the `--help` flag: + $ farm --help + $ farm build --help + $ farm watch --help + $ farm preview --help + $ farm clean --help + $ farm plugin --help + +Options: + -l, --lazy lazyCompilation + --host specify host + --port specify port + --open open browser on server start + --hmr enable hot module replacement + --cors enable cors + --strictPort specified port is already in use, exit with error + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging + -h, --help Display this message + -v, --version Display version number +``` + +## Start + +`farm start` 命令用于启动开发服务器, 将代码进行开发环境的编译 + +```json title="Terminal" +Usage: + $ farm [root] + +Options: + -l, --lazy lazyCompilation + --host specify host + --port specify port + --open open browser on server start + --hmr enable hot module replacement + --cors enable cors + --strictPort specified port is already in use, exit with error + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging +``` + + + +## Build + +`farm build` 命令会在默认的 `dist` 目录下构建出可用于生产环境的产物。 + +```json title="Terminal" +Usage: + $ farm build + +Options: + -o, --outDir output directory + -i, --input input file path + -w, --watch watch file change + --targetEnv transpile targetEnv node, browser + --format transpile format esm, commonjs + --sourcemap output source maps for build + --treeShaking Eliminate useless code without side effects + --minify code compression at build time + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging + -h, --help Display this message +``` + +## Preview + +`farm preview` 用于在本地可以直接预览您的生产环境构建出的产物, 您需要提前执行 `farm build` 来构建出生产环境的产物 + +```json title="Terminal" +Usage: + $ farm preview + +Options: + --open [url] 启动时是否在浏览器中打开页面 + --port 设置 Server 监听的端口号 + --host 指定 Server 启动时监听的 host + -c --config 指定配置文件路径 + -h, --help 显示命令帮助 +``` + +## Watch + +`farm watch` 一般作用于 `node` 环境下监听文件变化并且重新构建 + +```json title="Terminal" + +Usage: + $ farm watch + +Options: + --format transpile format esm, commonjs + -o, --outDir output directory + -i, --input input file path + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging + -h, --help Display this message +``` + +## Clean + +`farm clean` 由于 `farm` 提供的增量构建会在本地生成缓存文件, 如果在特定情况下(不可预知的编译错误)可能您需要清理缓存文件 + +```json title="Terminal" +Usage: + $ farm clean [path] + +Options: + --recursive Recursively search for node_modules directories and clean them + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging + -h, --help Display this message +``` diff --git a/docs/cli/preview.md b/docs/cli/preview.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/cli/start.md b/docs/cli/start.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/cli/watch.md b/docs/cli/watch.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/config/compilation-options.md b/docs/config/compilation-options.md index 95c44353c..e75df201f 100644 --- a/docs/config/compilation-options.md +++ b/docs/config/compilation-options.md @@ -3,12 +3,7 @@ By default, Farm reads the configuration from the `farm.config.ts|js|mjs` file in the project root directory, an example configuration file: ```ts title="farm.config.ts" -import type { UserConfig } from "@farmfe/core"; - -function defineConfig(config: Config) { - return config; -} - +import { defineConfig } from "@farmfe/core"; export default defineConfig({ root: process.cwd(), // compiled root directory // compile options @@ -36,9 +31,9 @@ All compilation-related configuration is under the `compilation` field. The entry point for the project. Input files can be `html`, `ts/js/tsx/jsx`, `css` or other files supported by plugins. ```tsx -import type { UserConfig } from "@farmfe/core"; +import { defineConfig } from "@farmfe/core"; -export default { +export default defineConfig({ compilation: { input: { index: "./index.html", @@ -457,7 +452,7 @@ type BrowserTargetsRecord = Partial< Configure which target browsers or browser versions to enable, for example: ```ts -import type { UserConfig } from "@farmfe/core"; +import { defineConfig } from "@farmfe/core"; function defineConfig(config: UserConfig) { return config; diff --git a/docs/config/dev-server.md b/docs/config/dev-server.md index ff03a9632..ec9365306 100644 --- a/docs/config/dev-server.md +++ b/docs/config/dev-server.md @@ -5,11 +5,7 @@ Configure the behavior of Farm Dev Server. Example: ```ts -import type { UserConfig } from "@farmfe/core"; - -function defineConfig(config: UserConfig) { - return config; -} +import { defineConfig } from "@farmfe/core"; export default defineConfig({ // All dev server options are under server @@ -98,7 +94,7 @@ Host on which the Web Socket server listens Configure server proxy. Based on [koa-proxies](https://www.npmjs.com/package/koa-proxies) implementation, specific options refer to its documentation, example: ```ts -import type { UserConfig } from "@farmfe/core"; +import { defineConfig } from "@farmfe/core"; function defineConfig(config: UserConfig) { return config; diff --git a/docs/features/html.md b/docs/features/html.md index 475a0846a..3dbf7b86f 100644 --- a/docs/features/html.md +++ b/docs/features/html.md @@ -3,18 +3,21 @@ sidebar_position: 1 --- # Html + ## Basic Usage + Farm support compile Html out of box, **and you should use Html as entry when build a web project**, for example: ```ts title="farm.config.ts" -import type { UserConfig } from '@farmfe/core'; +import type { defineConfig } from "@farmfe/core"; -export default { +export default defineConfig({ input: { - index: './index.html' // using ./index.html as entry - } -} + index: "./index.html", // using ./index.html as entry + }, +}); ``` + :::note If the input is not specified, default to `{ index: 'index.html' }`. ::: @@ -27,26 +30,25 @@ and in `./index.html`, a ` + - ``` + and you can also use `` to refer to your global css. Farm will transform these `scripts` and `links` to final production resources when compiling. Note that you have to use `relative path` when you want to refer to a local module, for example `` will refer to a local module and compile it, but `` or `` would not. - - :::tip The `script` and `link` can refer to any module types that farm support, for example, `js`, `jsx`, `ts`, `tsx`, or other module types supported by plugins. You can use as many `scripts` or `links` as you want. ::: ## Multi Page App + If you are building a Multi Page Application, just configure multiple html input, for example: ```ts title="farm.config.ts" -import type { UserConfig } from '@farmfe/core'; +import type { UserConfig } from "@farmfe/core"; export function defineConfig(config: UserConfig) { return config; @@ -55,20 +57,22 @@ export function defineConfig(config: UserConfig) { export default defineConfig({ compilation: { input: { - home: './index.html', // Home Page - about: './about.html', // About Page + home: "./index.html", // Home Page + about: "./about.html", // About Page // ... more pages - } - } -}) + }, + }, +}); ``` + Farm will compile these pages in parallel, and all dependencies of these pages will be shared too. ## Inherit html template + Farm supports inherit html template by using `html.base` config, which is helpful when building a multi-page application with html shared. ```ts title="farm.config.ts" -import type { UserConfig } from '@farmfe/core'; +import type { UserConfig } from "@farmfe/core"; export function defineConfig(config: UserConfig) { return config; @@ -78,17 +82,17 @@ export default defineConfig({ // ... compilation: { input: { - home: './index.html', // Home Page - about: './about.html', // About Page + home: "./index.html", // Home Page + about: "./about.html", // About Page // ... more pages }, // c-highlight-start html: { - base: './base.html' - } + base: "./base.html", + }, // c-highlight-end - } -}) + }, +}); ``` Then add a `base.html`, placeholder `{{children}}` will be replaced by children's content. @@ -96,17 +100,17 @@ Then add a `base.html`, placeholder `{{children}}` will be replaced by children' ```html title="./base.html" - - - - - Document - - -
- - {{children}} - + + + + + Document + + +
+ + {{children}} + ``` @@ -115,4 +119,4 @@ Inherit `./base.html`: ```html title="./src/home.html" -``` \ No newline at end of file +``` diff --git a/docs/plugins/writing-plugins/js-plugin.md b/docs/plugins/writing-plugins/js-plugin.md index badfdddc1..d219e8f50 100644 --- a/docs/plugins/writing-plugins/js-plugin.md +++ b/docs/plugins/writing-plugins/js-plugin.md @@ -1,27 +1,32 @@ -# Js Plugins -A Js plugin is a plain Javascript object. +# JavaScript Plugins + +:::tip{title="Js Plugins"} +A JavaScript plugin is simply a pure JavaScript object. +::: ```js // farm.config.ts -import { UserConfig } from '@farmfe/core'; +import { defineConfig } from "@farmfe/core"; -export default { +export default defineConfig({ // ... plugins: [ // a plugin object { - name: 'my-resolve-plugin', + name: "my-resolve-plugin", priority: 1000, // the priority of this plugin, the larger the value, the earlier the execution. Normally internal plugins is 100. resolve: { - filters: { // Only execute the hook when following conditions satisfied - sources: ['\\./index.ts'], // a regex array - importers: ['None'], + filters: { + // Only execute the hook when following conditions satisfied + sources: ["\\./index.ts"], // a regex array + importers: ["None"], }, - executor: async (param) => { // this hook executor + executor: async (param) => { + // this hook executor console.log(param); // resolve params // return the resolve result return { - resolvedPath: 'virtual:my-module', + resolvedPath: "virtual:my-module", query: {}, sideEffects: false, external: false, @@ -31,7 +36,7 @@ export default { }, // load, transform are similar to resolve, refer to their types ], -}; +}); ``` If you want to pass args to your plugins，you can use a closure. @@ -39,22 +44,22 @@ If you want to pass args to your plugins，you can use a closure. ```ts // my-resolve-plugin.ts export function myResolvePlugin(options: Options) { - const { xx } = options + const { xx } = options; return { - name: 'my-resolve-plugin', + name: "my-resolve-plugin", resolve: { // ... - } + }, }; } // farm.config.ts -import { defineFarmConfig } from '@farmfe/core/dist/config'; -import { myResolvePlugin } from './myResolvePlugin.ts'; +import { defineConfig } from "@farmfe/core"; +import { myResolvePlugin } from "./myResolvePlugin.ts"; -export default defineFarmConfig({ +export default defineConfig({ // ... - plugins: [myResolvePlugin({ xx:'xx' })], + plugins: [myResolvePlugin({ xx: "xx" })], }); -``` \ No newline at end of file +``` diff --git a/docs/quick-start.mdx b/docs/quick-start.mdx index 9aebf9585..2e2b8f738 100644 --- a/docs/quick-start.mdx +++ b/docs/quick-start.mdx @@ -33,8 +33,7 @@ Farm needs **Node 16 and above**. -:::note -Then follow the prompts! +:::note{title="Then follow the prompts!"} You can also directly specify the project name and the template you want to use via additional command line options: ::: @@ -85,9 +84,9 @@ The project will start at `http://localhost:9000` by default. The project is configured by `farm.config.ts/js/mjs` file in the root directory of the project. ```ts title="farm.config.ts" -import type { UserConfig } from "@farmfe/core"; +import { defineConfig } from "@farmfe/core"; -export default { +export default defineConfig({ // Options related to the compilation compilation: { input: { @@ -107,7 +106,7 @@ export default { }, // Additional plugins plugins: [], -}; +}); ``` :::note diff --git a/docusaurus.config.js b/docusaurus.config.js index ff8b5de5d..12b0e0376 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -193,8 +193,8 @@ const config = { content: `🎉 Farm will release 1.0 soon. If you like Farm, give it a ⭐️ on GitHub`, }, prism: { - theme: prismThemes.github, - darkTheme: prismThemes.dracula, + theme: prismThemes.nightOwlLight, + darkTheme: prismThemes.oneDark, magicComments: [ // Remember to extend the default highlight class name as well! { diff --git a/i18n/zh/code.json b/i18n/zh/code.json index e74d39257..ca57f452c 100644 --- a/i18n/zh/code.json +++ b/i18n/zh/code.json @@ -434,17 +434,20 @@ "Consistency": { "message": "一致性" }, - "Consistency: What you see in development will be the same as what you get in production.": { - "message": "一致性: 开发环境和生产环境的表现一致，所见即所得。" + "Written in Rust, start a React / Vue project in milliseconds and perform an HMR update within 10ms for most situations.": { + "message": "用Rust编写，可以在毫秒内启动React/Vue项目，并在大多数情况下在10毫秒内进行热模块替换（HMR）更新。" }, - "Compatibility: Supports both legacy (ES5) and modern browsers.": { - "message": "兼容性: 同时支持传统(ES5)和现代浏览器。" + "Consistency & Compatibility: What you see in development will be the same as what you get in production. Supports both legacy (ES5) and modern browsers.": { + "message": "一致性: 开发环境和生产环境的表现一致，所见即所得。支持传统（ES5）和现代浏览器。" + }, + "Incremental Building: Support persistent cache, module level cache enabled by default, any module won't be compiled twice until it's changed!": { + "message": "增量构建：默认启用, 支持持久缓存，模块级别缓存，任何模块在未发生变化之前不会被重新编译！" }, "Farm support compiling Html, Css, Css Modules, Js/Jsx/Ts/Tsx, Json, Static Assets out of box, support sass, less, postcss, vue, react, solid by official plugins, support lazy compiling, partial bundling and more": { "message": "丰富的编译能力支持: 开箱即用, Farm 内置了 Js/Ts/Jsx/Tsx、Css/Css Modules/Sass/Less、HTML 和静态资源，可以通过官方插件支持 sass、less、postcss、react、vue、solid 等常用技术栈，支持惰性编译、局部打包等。" }, - "Fully Pluggable: Everything inside Farm is powered by plugins, achieve anything you want by creating a plugin. Supports both Rust and JavaScript plugins.": { - "message": "Farm 由插件驱动, 通过创建插件来实现任何您想要的功能, 同时支持 Rust 和 JavaScript 两种插件模式。" + "Fully Pluggable: Everything inside Farm is powered by plugins, achieve anything you want by creating a plugin. Supports both Rust and JavaScript plugins. Support Vite plugins out of box.": { + "message": "Farm 由插件驱动, 通过创建插件来实现任何您想要的功能, 同时支持 Rust 和 JavaScript 两种插件模式, 开箱即用支持 Vite 插件。" }, "Partial Bundling: Bundle your project into a few reasonable bundles, speeding up resource loading without losing caching granularity.": { "message": "自动根据依赖关系、资源大小，将项目打包成若干个资源，提升资源加载性能的同时，保证缓存命中率。" @@ -455,6 +458,9 @@ "ColdStart": { "message": "冷启动" }, + "HotStart": { + "message": "热启动" + }, "HmrRoot": { "message": "热更新 (根模块)" }, @@ -463,5 +469,8 @@ }, "ColdBuild": { "message": "冷构建" + }, + "HotBuild": { + "message": "热构建" } } diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/hmr-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/api/hmr-api.md new file mode 100644 index 000000000..f92888fe3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/hmr-api.md @@ -0,0 +1 @@ +# Hmr Api diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/javascript-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/api/javascript-api.md new file mode 100644 index 000000000..d1daa55bc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/javascript-api.md @@ -0,0 +1 @@ +# JavaScript Api diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/js-plugin-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/api/js-plugin-api.md new file mode 100644 index 000000000..8e03502ca --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/js-plugin-api.md @@ -0,0 +1 @@ +# Js Plugin Api diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/rust-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/api/rust-api.md new file mode 100644 index 000000000..91a278a54 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/rust-api.md @@ -0,0 +1 @@ +# Rust Api diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/rust-plugin-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/api/rust-plugin-api.md new file mode 100644 index 000000000..da099bbc0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/rust-plugin-api.md @@ -0,0 +1 @@ +# Rust Plugin Api diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cli/cli-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/cli/cli-api.md new file mode 100644 index 000000000..5552492c6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cli/cli-api.md @@ -0,0 +1,172 @@ +# Farm CLI API + +The Farm CLI allows you to start, build, preview, and watch your application. + +To get a list of cli available to Farm, run the following command inside your command + +```json title="Terminal" +npx farm -h +``` + +The output look like this: + +```json title="Terminal" +farm/0.5.11 + +Usage: + $ farm [root] + +Commands: + [root] Compile the project in dev mode and serve it with farm dev server + build compile the project in production mode + watch watch file change + preview compile the project in watch mode + clean [path] Clean up the cache built incrementally + plugin [command] Commands for manage plugins + +For more info, run any command with the `--help` flag: + $ farm --help + $ farm build --help + $ farm watch --help + $ farm preview --help + $ farm clean --help + $ farm plugin --help + +Options: + -l, --lazy lazyCompilation + --host specify host + --port specify port + --open open browser on server start + --hmr enable hot module replacement + --cors enable cors + --strictPort specified port is already in use, exit with error + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging + -h, --help Display this message + -v, --version Display version number +``` + +## Start + +`farm start` 命令用于启动开发服务器, 将代码进行开发环境的编译 + +```json title="Terminal" +Usage: + $ farm [root] + +Options: + -l, --lazy lazyCompilation + --host specify host + --port specify port + --open open browser on server start + --hmr enable hot module replacement + --cors enable cors + --strictPort specified port is already in use, exit with error + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging +``` + + + +## Build + +`farm build` 命令会在默认的 `dist` 目录下构建出可用于生产环境的产物。 + +```json title="Terminal" +Usage: + $ farm build + +Options: + -o, --outDir output directory + -i, --input input file path + -w, --watch watch file change + --targetEnv transpile targetEnv node, browser + --format transpile format esm, commonjs + --sourcemap output source maps for build + --treeShaking Eliminate useless code without side effects + --minify code compression at build time + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging + -h, --help Display this message +``` + +## Preview + +`farm preview` 用于在本地可以直接预览您的生产环境构建出的产物, 您需要提前执行 `farm build` 来构建出生产环境的产物 + +```json title="Terminal" +Usage: + $ farm preview + +Options: + --open [url] 启动时是否在浏览器中打开页面 + --port 设置 Server 监听的端口号 + --host 指定 Server 启动时监听的 host + -c --config 指定配置文件路径 + -h, --help 显示命令帮助 +``` + +## Watch + +`farm watch` 一般作用于 `node` 环境下监听文件变化并且重新构建 + +```json title="Terminal" + +Usage: + $ farm watch + +Options: + --format transpile format esm, commonjs + -o, --outDir output directory + -i, --input input file path + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging + -h, --help Display this message +``` + +## Clean + +`farm clean` 由于 `farm` 提供的增量构建会在本地生成缓存文件, 如果在特定情况下(不可预知的编译错误)可能您需要清理缓存文件 + +```json title="Terminal" +Usage: + $ farm clean [path] + +Options: + --recursive Recursively search for node_modules directories and clean them + -c, --config use specified config file + -m, --mode set env mode + --base public base path + --clearScreen allow/disable clear screen when logging + -h, --help Display this message +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/config/compilation-options.md b/i18n/zh/docusaurus-plugin-content-docs/current/config/compilation-options.md index 665c8ff30..6498fb66a 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/config/compilation-options.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/config/compilation-options.md @@ -3,11 +3,7 @@ Farm 默认从项目根目录的 `farm.config.ts|js|mjs` 文件中读取配置，配置文件示例: ```ts title="farm.config.ts" -import type { UserConfig } from "@farmfe/core"; - -function defineConfig(config: Config) { - return config; -} +import { defineConfig } from "@farmfe/core"; export default defineConfig({ root: process.cwd(), // 编译的根目录 @@ -36,9 +32,9 @@ export default defineConfig({ 项目的入口点。 Input 的文件可以是`html`、`ts/js/tsx/jsx`、`css` 或通过插件支持的其他文件。 ```tsx -import type { UserConfig } from "@farmfe/core"; +import { defineConfig } from "@farmfe/core"; -export default { +export default defineConfig({ compilation: { input: { index: "./index.html", @@ -457,11 +453,7 @@ type BrowserTargetsRecord = Partial< 配置对于哪些目标浏览器或者浏览器版本开启，示例： ```ts -import type { UserConfig } from "@farmfe/core"; - -function defineConfig(config: UserConfig) { - return config; -} +import { defineConfig } from "@farmfe/core"; export default defineConfig({ compilation: { diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/config/plugins-options.md b/i18n/zh/docusaurus-plugin-content-docs/current/config/plugins-options.md index 6442a7496..14fdbd47c 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/config/plugins-options.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/config/plugins-options.md @@ -3,13 +3,8 @@ 配置 Farm 的插件，支持 Rust 插件或者 Js 插件，示例如下： ```ts -import type { UserConfig } from "@farmfe/core"; +import { defineConfig } from "@farmfe/core"; import less from "@farmfe/js-plugin-less"; - -function defineConfig(config: UserConfig) { - return config; -} - export default defineConfig({ plugins: ["@farmfe/plugin-react", "@farmfe/plugin-sass", less()], }); @@ -22,11 +17,7 @@ export default defineConfig({ Rust 插件通过 `插件名`或者 `[插件名, 配置项选项]` 方式配置，如下： ```ts -import type { UserConfig } from "@farmfe/core"; - -function defineConfig(config: UserConfig) { - return config; -} +import { defineConfig } from "@farmfe/core"; export default defineConfig({ plugins: [ diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/features/html.md b/i18n/zh/docusaurus-plugin-content-docs/current/features/html.md index 6e31d4f62..47f1962a5 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/features/html.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/features/html.md @@ -3,17 +3,19 @@ sidebar_position: 1 --- # Html + ## 基本用法 + Farm 支持开箱即用地编译 Html，并且在构建 Web 项目时应该使用 Html 作为入口，例如： ```ts title="farm.config.ts" -import type { UserConfig } from '@farmfe/core'; +import type { UserConfig } from "@farmfe/core"; -export default { +export default defineConfig({ input: { - index: './index.html' // using ./index.html as entry - } -} + index: "./index.html", // using ./index.html as entry + }, +}); ``` :::note @@ -28,40 +30,43 @@ export default {
- + - ``` -你也可以使用``来引用你的全局CSS。 -Farm在编译时会将这些 `script` 和 `link` 转化为最终的生产可用的产物。请注意，当您想引用本地模块时，必须使用 `相对路径`，例如 `` 将引用本地模块并编译它， 但 `` 或 `` 则不会。 +你也可以使用``来引用你的全局 CSS。 + +Farm 在编译时会将这些 `script` 和 `link` 转化为最终的生产可用的产物。请注意，当您想引用本地模块时，必须使用 `相对路径`，例如 `` 将引用本地模块并编译它， 但 `` 或 `` 则不会。 :::note `script` 和 `link` 可以引用 farm 支持的任何模块类型，例如，`js`、`jsx`、`ts`、`tsx` 或插件支持的其他模块类型。 您可以根据需要使用任意数量的 `script` 或 `link`。 ::: ## 多页面应用程序 - MPA + 如果您正在构建多页面应用程序，只需配置多个 html，例如： ```ts title="farm.config.ts" import type { UserConfig } from '@farmfe/core'; -export default { +export default defineConfig({ input: { home: './index.html', // Home Page about: './about.html', // About Page // ... more pages } -} +}) ``` + Farm 将并行编译这些页面。 -## 继承html模板 +## 继承 html 模板 + Farm 支持通过使用 `html.base` 配置继承 html 模板，这在构建共享 html 的多页面应用程序时很有帮助。 ```ts title="farm.config.ts" -import type { UserConfig } from '@farmfe/core'; +import type { UserConfig } from "@farmfe/core"; export function defineConfig(config: UserConfig) { return config; @@ -71,15 +76,15 @@ export default defineConfig({ // ... compilation: { input: { - home: './index.html', // Home Page - about: './about.html', // About Page + home: "./index.html", // Home Page + about: "./about.html", // About Page // ... more pages }, html: { - base: './base.html' - } - } -}) + base: "./base.html", + }, + }, +}); ``` 然后添加一个`base.html`，占位符`{{children}}`将被替换为子 html 的内容。 @@ -87,23 +92,23 @@ export default defineConfig({ ```html title="./base.html" - - - - - Document - - -
- - {{children}} - + + + + + Document + + +
+ + {{children}} + -```` +``` 继承`./base.html`： ```html title="./src/home.html" -```` \ No newline at end of file +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/plugins/writing-plugins/js-plugin.md b/i18n/zh/docusaurus-plugin-content-docs/current/plugins/writing-plugins/js-plugin.md index 23a80a38a..b8c2298e2 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/plugins/writing-plugins/js-plugin.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/plugins/writing-plugins/js-plugin.md @@ -56,4 +56,4 @@ export default defineFarmConfig({ // ... plugins: [myResolvePlugin({ xx:'xx' })], }); -``` \ No newline at end of file +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/quick-start.mdx b/i18n/zh/docusaurus-plugin-content-docs/current/quick-start.mdx index e00c1cf0b..36df1f136 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/quick-start.mdx +++ b/i18n/zh/docusaurus-plugin-content-docs/current/quick-start.mdx @@ -78,9 +78,9 @@ Farm 需要 **Node 16 及以上**。 该项目由项目根目录中的“farm.config.ts/js/mjs”文件进行配置。 ```ts title="farm.config.ts" -import type { UserConfig } from "@farmfe/core"; +import { defineConfig } from "@farmfe/core"; -export default { +export default defineConfig({ // 编译相关配置 compilation: { input: { @@ -100,7 +100,7 @@ export default { }, // 插件配置 plugins: [], -}; +}); ``` :::note diff --git a/package.json b/package.json index b04d976d7..9531a1010 100644 --- a/package.json +++ b/package.json @@ -53,6 +53,7 @@ "@docusaurus/module-type-aliases": "3.0.1", "@docusaurus/types": "3.0.1", "@swc/core": "^1.3.99", + "shikiji": "^0.9.10", "swc-loader": "^0.2.3", "ts-node": "^10.9.1" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 3f4f7c625..cec2a40bf 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -94,6 +94,9 @@ devDependencies: '@swc/core': specifier: ^1.3.99 version: 1.3.101 + shikiji: + specifier: ^0.9.10 + version: 0.9.10 swc-loader: specifier: ^0.2.3 version: 0.2.3(@swc/core@1.3.101)(webpack@5.88.2) @@ -9854,6 +9857,16 @@ packages: rechoir: 0.6.2 dev: false + /shikiji-core@0.9.10: + resolution: {integrity: sha512-s+aC66Fh343wpm7VyQTg+htdHM/tUb8R+yxdAdUpCtKkRWbSBIpqQ3xTSNjbCTnGv10xsT164SW0r1VV1N6ToA==} + dev: true + + /shikiji@0.9.10: + resolution: {integrity: sha512-tqnoSWWb7NailWJ/72Bgi8Z5O+ul71SJ5EhXbfHprZg67RGwck5eVyv5Uv4pso06ZuzNpUabRTyyFKHN/Ea9Mw==} + dependencies: + shikiji-core: 0.9.10 + dev: true + /side-channel@1.0.4: resolution: {integrity: sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==} dependencies: diff --git a/sidebars.js b/sidebars.js index 819a92949..21ed28aff 100644 --- a/sidebars.js +++ b/sidebars.js @@ -72,11 +72,23 @@ const sidebars = { "config/plugins-options", ], }, + { + type: "category", + label: "Api Reference", + collapsed: false, + items: [ + "api/hmr-api", + "api/js-plugin-api", + "api/rust-plugin-api", + "api/javascript-api", + "api/rust-api", + ], + }, { type: "category", label: "CLI", collapsed: false, - items: ["cli/start", "cli/build", "cli/preview", "cli/watch"], + items: ["cli/cli-api"], }, // "config/farm-config", // "config/cli", diff --git a/src/css/_admonition.scss b/src/css/_admonition.scss index 1a2fe7be1..365671537 100644 --- a/src/css/_admonition.scss +++ b/src/css/_admonition.scss @@ -3,27 +3,27 @@ html[data-theme="light"] { --admonition-note-c-bg: linear-gradient(to bottom, var(--ifm-alert-note-background-color), - transparent); + transparent 40%); ; --admonition-info-c-bg: linear-gradient(to bottom, var(--ifm-alert-info-background-color), - transparent); + transparent 40%); ; --admonition-tip-c-bg: linear-gradient(to bottom, var(--ifm-alert-tip-background-color), - transparent); + transparent 40%); ; --admonition-warning-c-bg: linear-gradient(to bottom, var(--ifm-alert-warning-background-color), - transparent); + transparent 40%); ; --admonition-caution-c-bg: linear-gradient(to bottom, var(--ifm-alert-caution-background-color), - transparent); + transparent 40%); ; --admonition-danger-c-bg: linear-gradient(to bottom, var(--ifm-alert-danger-background-color), - transparent); + transparent 40%); ; --admonition-note-c-color: inherit; @@ -39,9 +39,9 @@ html[data-theme="light"] { --admonition-code-caution-c-bg: var(--c-orange-20); --admonition-code-danger-c-bg: var(--c-red-10); --admonition-tip-border: var(--c-green-10); - --ifm-alert-warning-background-color: var(--c-yellow-210); + --ifm-alert-warning-background-color: var(--c-yellow-10); --ifm-alert-tip-background-color: var(--c-green-10); - --ifm-alert-danger-background-color: var(--c-red-30); + --ifm-alert-danger-background-color: var(--c-red-10); --ifm-alert-note-background-color: #ff9ff360; --ifm-alert-info-background-color: var(--c-teal-10); --ifm-alert-caution-background-color: var(--c-green-10); @@ -203,4 +203,4 @@ html[data-theme="dark"] { .alert--secondary { // color: var(--ifm-font-color-base); -} \ No newline at end of file +}