编写 Rust 插件

用 Rust 写你的插件是一个推荐的方式，因为 Rust 插件比 JavaScript 插件更快和富有表现力。一个 Rust 插件应该是实现了 farmfe_core::plugin::Plugin trait 的 struct, 例如

#![deny(clippy::all)]

use farmfe_core::{config::Config, plugin::Plugin};

use farmfe_macro_plugin::farm_plugin;

// define your rust plugins
#[farm_plugin]
pub struct FarmPluginExample {}

impl FarmPluginExample {
  // 一个 Rust 插件必须导出一个名称是 new 的函数 并且初始化的时候接受两个参数
  fn new(config: &Config, options: String) -> Self {
    Self {}
  }
}
// 实现插件的 trait 来定义插件 hooks
impl Plugin for FarmPluginExample {
  fn name(&self) -> &str {
    "FarmPluginExample"
  }

  // more hooks here
}

Rust 插件注意事项：

• struct 必须是 pub 并且需要有 #[farm_plugin] 属性
• struct 必须实现 Plugin trait, 并且 name 方法必须要实现
• struct 必须导出一个 new 的方法，在初始化的时候接受两个参数 第一个参数是 &Config, 第二个参数是 String。new 方法在插件加载的时候调用。 Config 是 farm 项目的配置 String 是插件的选项

我们同时提供了 Rust 插件示例代码仓库：farm-rust-plugin-example

备注

本文章仅仅涵盖如何创建，开发和发布一个 Rust 插件，更多的细节参考 插件 Hooks

约定

对于特定的 Farm 插件

• 一个 Farm 的 Rust 插件应该有一个 farm-plugin- 前缀的名称并且语义清晰
• package.json 里面有 farm-plugin- 关键字

如果你的插件仅仅适配特定框架，其名称应遵循以下前缀格式:

• farm-plugin-vue-: 作为 Vue 插件前缀
• farm-plugin-react-: 作为 React 插件前缀
• farm-plugin-svelte-: 作为 Svelte 插件前缀
• ...

概念

在开始编写 Rust 插件之前，你应该了解以下概念:

• module_type：模块的类型，他可能是 js, ts, css, sass, json 等等。Farm 原生支持 js/ts/jsx/tsx, css, html, json, static asserts(png, svg等等)。module_type 会被 load 或者 transform 钩子返回
• resolved_path 和 module_id：resolved_path 是一个模块的绝对路径，module_id是一个模块的唯一 id，通常是模块对于项目根目录的相对路径 + query。例如 我们引用了一个模块 import './a?query' resolved_path 是 /project/src/a.ts module_id 是 src/a.ts?query
• context: 所有的插件都会接受一个 context 参数，它有 Farm 项目的整个编译上下文，你可以从里面拿到 ModuleGraph，Module，Resources等等
• Resource and Resource Pot：Resource 是输出出来的最终打包产物， Resource Pot是资源的抽象表示，类似于其他打包器的 Chunk。在 Farm 项目中，我们首先从 ModuleGraph 生成 Resource Pots, 渲染 Resource Pots，最终从 Resource Pots 生成 `Resource

模块类型

在 Farm 中，一切都被认为是“一等公民”，因此 Farm 设计 module_type 来标识模块类型，并在用不同的插件处理不同的模块类型 Module_type 由 load 钩子返回，并且可以由 transform 钩子转换。Farm 原生支持 js/ts/jsx/tsx、css、html、json、static assets(png、svg等)。对于这些模块类型，你可以直接在 load 或 transform hook 中返回。但是如果你想处理自定义模块类型，你需要实现其他钩子例如 parse， render_resource_pot_modules， generate resources 等来控制如何对自定义模块进行类型解析，渲染和生成资源。

创建插件

Farm 提供了官方模板来帮助你快速创建 Rust 插件:

pnpm

pnpm create farm-plugin

npm

npm create farm-plugin@latest

yarn

yarn create farm-plugin

然后按照提示创建插件

或者直接运行以下命令创建插件:

pnpm

pnpm create farm-plugin my-farm-plugin --type rust

npm

npm create my-farm-plugin --type rust

yarn

yarn create my-farm-plugin --type rust

上面的命令会在当前目录中创建一个名为 my-farm-plugin 的js插件。——type 可以是 rust 或者 js

插件项目结构

一个插件项目结构如下：

my-farm-plugin
├── .github
│   └── workflows
|       ├── release.yml
|       ├── build.yml
│       └── ci.yml
├── Cargo.toml
|── .gitignore
├── npm
│   ├── darwin-x64
│   ├── linux-x64-gnu
|   ├── win32-x64-msvc
│   └── ...
├── package.json
├── src
│   └── lib.rs
└── rust-toolchain.toml

值得注意的文件和目录:

• src/lib.rs: 插件的主要文件，你在这里定义你的插件
• Cargo.toml: Rust 项目的清单
• package.json: npm 项目清单
• npm: 平台特定的二进制包所在的位置。在发布插件之前，这些包应该发布到 npm registry
• .github/workflows: 用于在 github actions 中交叉构建和发布插件
• rust-toolchain.toml: rust 工具链文件，它不应该 被手动修改，它应该始终使用 与 farm core相同的版本。

Farm 提供了一个工具 (@farmfe/plugin-tools) 来帮助你构建和发布插件，参考 package.json:

{
  // ...
  "scripts": {
    // build your plugin for current platform
    "build": "farm-plugin-tools build --platform --cargo-name my_farm_plugin -p my_farm_plugin --release",
    // publish all platform packages under npm directory to npm registry
    "prepublishOnly": "farm-plugin-tools prepublish"
  },
  // ...
}

更多关于构建和发布的细节参考 构建 和 发布章节：

开发插件

为了在本地开发和测试你的插件 你首先依据你平台构建插件，运行：

pnpm build

然后你可以使用你构建好的插件，在 frame.config.ts 的 plugins添加你的插件：

import { defineConfig } from '@farmfe/core';

export default defineConfig({
  plugins: [
    'my-farm-plugin'
  ]
});

在你的 farm 项目中运行 pnpm i 并且运行 farm start 来运行你的带有你插件的 farm 项目 当对插件进行更改时，应该重新构建插件并重启 farm 项目以查看更改。例如，在你的插件中添加 load 钩子:

src/lib.rs

// ... ignore other code

impl Plugin for FarmPluginExample {
  fn name(&self) -> &str {
    "FarmPluginExample"
  }

  fn load(
    &self,
    param: &farmfe_core::plugin::PluginLoadHookParam,
    _context: &std::sync::Arc<farmfe_core::context::CompilationContext>,
    _hook_context: &farmfe_core::plugin::PluginHookContext,
  ) -> farmfe_core::error::Result<Option<farmfe_core::plugin::PluginLoadHookResult>> {
    println!(
      "load path: {:?}, id: {:?}",
      param.resolved_path, param.module_id
    );
    Ok(None)
  }
}

然后用 pnpm build 重新构建你的插件，用 farm start 重新启动你的 farm 项目，你会看到 load 钩子在编译你的 farm 项目时被调用。

备注

想了解更多关于插件 hooks , 参阅 插件钩子.

处理 ModuleType

module_type 由 load hook 或 transform hook 返回。你在 load hook 中可以给 module 设置任意的 module type，该模块将由支持该模块类型的相应插件处理。 对于原生支持的模块类型，你可以在 load 钩子中返回模块类型:

src/lib.rs

// ... ignore other code

impl Plugin for FarmPluginExample {
  fn name(&self) -> &str {
    "FarmPluginExample"
  }

  fn load(
    &self,
    param: &farmfe_core::plugin::PluginLoadHookParam,
    _context: &std::sync::Arc<farmfe_core::context::CompilationContext>,
    _hook_context: &farmfe_core::plugin::PluginHookContext,
  ) -> farmfe_core::error::Result<Option<farmfe_core::plugin::PluginLoadHookResult>> {
    // handle virtual module
    if param.module_id.starts_with("virtual:my-css:css") {
      // return module type and content
      Ok(Some(farmfe_core::plugin::PluginLoadHookResult {
        module_type: "css".to_string(),
        content: ".red { color: red; }".to_string(),
        ..Default::default()
      }))
    } else {
      Ok(None)
    }
  }
}

对于原生支持的模块类型，你应该使用 transform hook 将模块类型转换为原生支持的模块类型，否则你需要实现 parse、renderResourcePot hook 来处理你的自定义模块类型:

src/lib.rs

// ... ignore other code

impl Plugin for FarmPluginExample {
  fn name(&self) -> &str {
    "FarmPluginExample"
  }

  fn transform(
    &self,
    param: &farmfe_core::plugin::PluginTransformHookParam,
    _context: &std::sync::Arc<farmfe_core::context::CompilationContext>,
    _hook_context: &farmfe_core::plugin::PluginHookContext,
  ) -> farmfe_core::error::Result<Option<farmfe_core::plugin::PluginTransformHookResult>> {
    // module type guard is required
    if matches!(param.module_type, ModuleType::Custom("sass")) {
      // compile sass and transform the module type from sass to css
      Ok(Some(farmfe_core::plugin::PluginTransformHookResult {
        module_type: "css".to_string(),
        content: compileSass(param.content),
        ..Default::default()
      }))
    } else {
      Ok(None)
    }
  }
}

备注

模块类型保护，如 matches!(module_type, ModuleType::Custom("sass")) transform 钩子是必需的，因为所有模块类型都会调用 transform 钩子，并且你应该只在 transform hook 中处理你的自定义模块类型。parse和其他 hook 也是如此。

或者实现 parse，render_resource_pot_modules 钩子来处理你的自定义模块类型 参考 farm 如何原生处理 css 插件如何处理 css 模块类型的 farm-plugin-css

处理插件选项

rust 插件选项可以在farm.config.ts中配置:

import { defineConfig } from '@farmfe/core';

export default defineConfig({
  plugins: [
    ['my-farm-plugin', {
      // plugin options
      myOption: 'myOption'
    }]
  ]
});

该选项将被 json 序列化并传递给插件的new方法，你可以在new方法中处理该选项:

src/lib.rs

// ... ignore other code

// define your rust plugin options
#[derive(serde::Deserialize)]
pub struct Options {
  pub my_option: Option<String>,
}

impl FarmPluginExample {
  fn new(config: &Config, options: String) -> Self {
    // deserialize the options
    let my_option: Options = serde_json::from_str(&options).unwrap();
    // handle the options...
    Self {}
  }
}

请注意，你应该将依赖 serde 和 serde_json 添加到你的Cargo.toml中。来支持反序列化:

[dependencies]
# ... ignore other code
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

备注

不能被 json 序列化选项不被支持。这意味着你只能使用字符串、数字、布尔值、数组、对象等类型。不支持函数选项。

在插件里面使用 farm_core

Farm 在 farmfe_core crate 中暴露所有核心结构和工具函数。更多细节请参阅farmfe_core文档。

备注

如果你想在插件中使用 swc 中的 Module、Program 等结构，你应该使用由 farm_core 重新暴露的 farmfe_core::swc_ast。因为 farm_core 使用的 swc 版本可能与你在插件中使用的 swc 版本不同，并且 farm_core 使用的 swc 版本保证与 farm_core 兼容。

警告

在插件中使用 SWC

请注意，你的 rust 插件不应该使用任何与 SWC 相关的包，如swc_common、swc_transforms等。SWC 在进程中存储全局状态，当你在插件中使用 SWC 时，它可能会导致死锁。

如果你想要修改你的 Farm 项目的AST，建议写[SWC Plugin](/zh/docs/using-plugins#using-swc plugins)。关于如何编写SWC插件，请参阅编写SWC插件。

选择 Rust 工具链

因为 Farm 的 Rust 插件是一个动态链接库，你应该始终使用和 farm core 相同版本的 Rust 工具链。rust 工具链定义在 rust-toolchain.toml中。它不应该被手动修改。 并且应该始终使用 Rust 构建插件，因为Farm Core 不支持 FFI，也不承诺 ABI 稳定性以提供最佳性能。

插件的兼容性

Farm core 维护了一个向插件暴漏出来一个 API 版本。如果你遇到类似Incompatible Rust Plugin: Current core's version…，这意味着你的插件与当前 farm core版本不兼容。你应该更新你的插件到最新版本来解决这个问题。

对于插件作者来说，你应该重新用最新的 farm core 版本构建和发布插件，来让你的插件与最新的 farm core版本兼容。

备注

Farm 承诺与相同主版本的 AP I兼容，例如，如果你的插件兼容 Farm core 1.0.0，那么它也应该兼容 Farm core 1.1.0、1.2.0等，这意味着你的插件将始终适用于相同的 Farm 主版本。

交叉构建

一个 Farm Rust 插件是一个特定于平台的动态链接库，你应该为你想要支持的所有平台构建插件。 Farm 提供了一个使用 github actions 构建插件的示例，请参阅.github/workflows/build.yml

默认情况下，farm rust 插件应该针对以下平台构建:

• linux-x64-gnu
• linux-x64-musl
• darwin-x64
• win32-x64-msvc
• linux-arm64-musl
• linux-arm64-gnu
• darwin-arm64
• win32-ia32-msvc
• win32-arm64-msvc

对于公开发布到 npm registry 的插件，建议发布支持上面所有平台的插件。对于私有 rust 插件，你可以为任何你想支持的平台构建插件。

提示

因为 rust 插件是一个纯动态链接库，如果您有关于如何为特定平台构建插件的问题，只需谷歌如何在 rust 中为该平台构建动态链接库。

发布

发布 Rust插件的有以下的步骤:

1. 交叉构建动态链接库的 Rust 插件，详情请参阅交叉构建
2. 将二进制文件复制到 npm 目录下，例如:复制到 npm/linux-x64-gnu/index.farm
3. 在 npm 目录下发布平台特定的包，你可以使用farm-plugin-tool prepublish在 npm 目录下发布包
4. 发布包本身

参见示例github actions publish workflow

例子

我们将使用 @farmfe/plugin-sass 作为一个真正的 Rust 插件示例。这个插件将支持在你的项目中编译.scss 和 .sass 文件

定义一个插件

导出一个名为 FarmPluginSass 的 Rust struct

src/lib.rs

use farmfe_macro_plugin::farm_plugin;

// 1. define a struct with #[farm_plugin] attribute
#[farm_plugin]
pub struct FarmPluginSass {
  sass_options: String,
  regex: Regex,
}

impl FarmPluginSass {
  // 2. define a new method with 2 arguments
  pub fn new(_config: &Config, options: String) -> Self {
    Self {
      sass_options: options,
      regex: Regex::new(r#"\.(sass|scss)$"#).unwrap(),
    }
  }
}

• struct 必须是pub并且必须有 #[farm_plugin] 属性。
• 结构体必须导出一个new方法，该方法接受两个参数作为初始化参数，第一个参数是&Config，第二个参数是String。

实现插件 Trait

Plugin trait 用于定义可以挂接到 farm compiler 的 hooks

use farmfe_core::plugin::Plugin;
use farmfe_macro_plugin::farm_plugin;

// 1. define a struct with #[farm_plugin] attribute
#[farm_plugin]
pub struct FarmPluginSass {
  sass_options: String,
  regex: Regex,
}

impl FarmPluginSass {
  // 2. define a new method with 2 arguments
  pub fn new(_config: &Config, options: String) -> Self {
    Self {
      sass_options: options,
      regex: Regex::new(r#"\.(sass|scss)$"#).unwrap(),
    }
  }
}
// Implement Plugin Trait
impl Plugin for FarmPluginSass {
  fn name(&self) -> &str {
    "FarmPluginSass"
  }

  // this plugin should be executed before internal plugins
  fn priority(&self) -> i32 {
    101
  }
}

加载 .scss 文件

实现 load 钩子以支持加载 .scss 文件

// ignore other code ...

// Implement Plugin Trait
impl Plugin for FarmPluginSass {
  fn name(&self) -> &str {
    "FarmPluginSass"
  }

  // this plugin should be executed before internal plugins
  fn priority(&self) -> i32 {
    101
  }

  fn load(
    &self,
    param: &farmfe_core::plugin::PluginLoadHookParam,
    _context: &std::sync::Arc<farmfe_core::context::CompilationContext>,
    _hook_context: &farmfe_core::plugin::PluginHookContext,
  ) -> farmfe_core::error::Result<Option<farmfe_core::plugin::PluginLoadHookResult>> {
    if param.query.is_empty() && self.regex.is_match(param.resolved_path) {
      let content = fs::read_file_utf8(param.resolved_path);

      if let Ok(content) = content {
        return Ok(Some(farmfe_core::plugin::PluginLoadHookResult {
          content,
          module_type: ModuleType::Custom(String::from("sass")),
        }));
      }
    }

    Ok(None)
  }
}

在 load 钩子中，我们只读取以.scss 或者 .sass结尾的文件,返回文件内容并将其 module_type 设置为ModuleType::Custom(String::from("sass"))。

转化 sass 文件

加载 .scss 文件之后，我们需要在 transform hook 中将其转换为 css，然后 Farm 将在接下来的过程中将其视为 css

// ignore other code ...
fn transform(
  &self,
  param: &farmfe_core::plugin::PluginTransformHookParam,
  context: &std::sync::Arc<farmfe_core::context::CompilationContext>,
) -> farmfe_core::error::Result<Option<farmfe_core::plugin::PluginTransformHookResult>> {
  // module type guard is neccessary
  if param.module_type == ModuleType::Custom(String::from("sass")) {
    // ... ignore other code

    // parse options
    const options = parse_options(&self.options, param.module_id);
    // compile sass to css
    let compile_result = compileSass(&param.content, options);

    return Ok(Some(farmfe_core::plugin::PluginTransformHookResult {
      content: compile_result.css,
      source_map: compile_result.source_map,
      // tell farm compiler that we have transformed this module to css
      module_type: Some(farmfe_core::module::ModuleType::Css),
      ignore_previous_source_map: false,
    }));
  }

  Ok(None)
}

提示

这个例子只介绍了如何实现转换器。有关 Farm 支持的更多能力，请参阅插件钩子。