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.

tip

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:

farm.config.ts

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:

farm.config.ts

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:

farm.config.ts

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, uses sass-embedded internally.

tip

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:

farm.config.ts

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:

farm.config.ts

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:

farm.config.ts

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'
          }
        }
      }
    }
  ],
});

note

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.

tip

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.

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:

farm.config.ts

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:

farm.config.ts

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' })],
    }),
  ]
});

note

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.

tip

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 resolvedPaths and moduleTypes these two filter items, if both are specified at the same time, take the union.

note

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.