Using Plugins
There are 4 kinds of plugins supported in Farm:
Farm Compilation Plugins: Support both Rust Plugins and Js Plugins, which adopt a rollup-style hooks.Vite/Rollup/Unplugin Plugin: Vite/Rollup/Unplugin plugins are supported in Farm out of Box.Farm Runtime Plugin: Adding abilities for Farm's runtime system.Swc Plugins: Swc plugins are supported in Farm out of Box.
Farm adopt Vite/Rollup ecosystem, Vite/Rollup Plugins can be used directly in Farm.
For how to write your own plugins, refer to Writing Plugins
Farm Compilation Plugins
First, install the plugins your need, for example:
pnpm add -D @farmfe/plugin-sass @farmfe/js-plugin-postcss
Using plugins to configure Farm compilation plugins:
import farmPostcssPlugin from "@farmfe/js-plugin-postcss";
export default defineConfig({
// ...
plugins: [
// Rust plugin, configure its package name
"@farmfe/plugin-sass",
// Js plugin, configure the plugin object
farmPostcssPlugin()
],
});
There are 2 kinds of Farm compilation plugins:
Rust Plugins: which is written in Rust and has best performance.Js Plugins: which is written in JS/TS, and it's used for compatibility with current JS ecosystem
Using Rust Plugins
Using package name to configure a Rust Plugin, for example:
export default defineConfig({
// ...
plugins: [
// Rust plugin, configure its package name
"@farmfe/plugin-sass",
],
});
For above example, Farm will resolve package @farmfe/plugin-sass and treat it as a Farm Rust Plugin.
If you want to configure options for rust plugins, you can use array syntax like [packageName, optionsObject], for example:
export default defineConfig({
// ...
plugins: [
// using array syntax to configure a rust plugin
[
// rust plugin's name
"@farmfe/plugin-sass",
// rust plugin's options
{
additionalData: '@use "@/global-variables.scss";'
}
],
],
});
Currently Farm supports 2 rust plugins officially:
@farmfe/plugin-react: Farm rust plugin for react jsx compilation and react-refresh injection.@farmfe/plugin-sass: Farm rust plugin for scss files compilation, usessass-embeddedinternally.
To learn more about rust plugins, see Rust Plugins
Using Js Plugins
Farm JS plugin is a JS object with methods as hooks, for example:
import farmPostcssPlugin from "@farmfe/js-plugin-postcss";
export default defineConfig({
plugins: [
// Js plugin, configure the plugin object
farmPostcssPlugin({
// ... configure postcss options
})
],
});
farmPostcssPlugin() returns a plugin object, and you can pass any postcss options by its arguments.
You can use priority to control the order of your plugins, for example:
import farmPostcssPlugin from "@farmfe/js-plugin-postcss";
export default defineConfig({
plugins: [
// Js plugin, configure the plugin object
{
...farmPostcssPlugin({
// ... configure postcss options
}),
// larger priority will be executed first, priority of internal plugin are 100.
priority: 1000,
}
],
});
priority of internal plugin are 100, if you want the plugin execute first, set it larger than 100, otherwise set it smaller than 100.
If you want to add a Farm JS plugin quickly, you can just configure a plugin object:
import readFileSync from 'fs';
export default defineConfig({
plugins: [
// configure a custom plugin
{
// plugin name, required
name: 'my-first-farm-plugin',
// this priority of this plugin, bigger value will be executed first, default to 100.
priority: 1000,
// define a load hook to determine how to load a more
load: {
// to improve performance, modules will be skipped if they don't match the filters.
filters: {
// only be executed for .png files.
resolvedPaths: ['\\.png$']
},
// executor callback for this hook
executor: (params, context) => {
const { resolvedPath } = params;
const content = readFileSync(resolvedPath, 'utf-8');
return {
content: `export default '${content}'`,
moduleType: 'js'
}
}
}
}
],
});
filters is required in Farm for js plugins. Because Js Plugin is really slow and we should avoid executing it as much as possible. For those modules that don't match the filters, Farm won't trigger js plugin hook for them at all! Which means Farm can handle them only on Rust side safely and concurrently.
To learn more about Farm Js Plugins, refer to JS Plugin
Using Vite/Rollup/Unplugin Plugins In Farm
Farm supports Vite plugins out of Box. First you need to install vite plugins，for example:
pnpm add @vitejs/plugin-vue @vitejs/plugin-vue-jsx vite -D
Then you can use vite plugins directly by vitePlugins in farm.config.ts.
import vue from '@vitejs/plugin-vue',
import vueJsx from '@vitejs/plugin-vue-jsx';
export default defineConfig({
// configuring vite plugins
vitePlugins: [
vue(),
vueJsx()
]
});
To improve performance of vite plugins, you can use function syntax that returns a filters, for example:
import vue from '@vitejs/plugin-vue',
// Using function syntax of Vite plugin
function configureVitePluginVue() {
// return plugin and its filters
return {
// using plugin vue
vitePlugin: vue(),
// configuring filters for it. Unmatched module paths will be skipped.
filters: ['\\.vue$', '\\\\0.+']
};
}
export default defineConfig({
// configuring vite plugins
vitePlugins: [
configureVitePluginVue
]
});
Using unplugin：
pnpm add unplugin-auto-import unplugin-vue-components -D
configuring unplugin in vitePlugins via unplugin/vite or unplugin/rollup:
import vue from '@vitejs/plugin-vue',
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
export default defineConfig({
vitePlugins: [
vue(),
// ...
AutoImport({
resolvers: [ElementPlusResolver({ importStyle: 'sass' })],
}),
Components({
resolvers: [ElementPlusResolver({ importStyle: 'sass' })],
}),
]
});
Currently you can use unplugin/vite or unplugin/rollup. unplugin/farm will be available as soon as this unplugin PR merged.
Farm Runtime Plugin
Farm has a runtime module system to control how to load and execute modules. Configuring compilation.runtime.plugins to add more runtime plugin, for example:
export default defineConfig({
compilation: {
// configure Farm runtime module system
runtime: {
plugins: [
// a runtime plugin package
require.resolve('farm-plugin-runtime-mock'),
// a local runtime plugin
path.join(process.cwd(), "build/runtime-plugin.ts")
]
}
}
});
you have to configure a path that point to your runtime plugin's entry. Recommend to a absolute path to avoid path issue.
To learn more about runtime plugin refer to Runtime Plugin
Using SWC Plugins
Swc Plugin can also be used directly in Farm, Configuring compilation.script.plugins to add SWC plugins, for example:
import jsPluginVue from '@farmfe/js-plugin-vue';
/**
* @type {import('@farmfe/core').UserConfig}
*/
export default {
compilation: {
script: {
plugins: [{
// the package name of the swc plugin
name: 'swc-plugin-vue-jsx',
// options of this swc plugin
options: {
"transformOn": true,
"optimize": true
},
// plugin execute when the filters are matched.
filters: {
// resolvedPaths: [".+"]
moduleTypes: ['tsx', 'jsx'],
}
}]
}
},
plugins: [jsPluginVue()],
};
Each plugin item of the array contains three fields:
- name: the package name of the swc plugin
- options: Configuration items passed to swc plugin
- filters: Which modules to execute the plug-in, must be configured, support
resolvedPathsandmoduleTypesthese two filter items, if both are specified at the same time, take the union.
SWC plugin may not be compatible with the SWC version(rust crate swc_core v0.90) that Farm uses. If a error occurred, try upgrade the plugin version.