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.

Farm Compilation Plugins

First, install the plugins your need, for example:

bash

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, powered by grass.

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

Using Vite/Rollup/Unplugin Plugins In Farm

Farm supports Vite plugins out of Box. First you need to install vite plugins，for example:

bash

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�?

bash

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

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.

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.