Plugin Development

Plugins Overview

A Rollup plugin is an object with one or more of the properties, build hooks, and output generation hooks described below, and which follows our conventions. A plugin should be distributed as a package which exports a function that can be called with plugin specific options and returns such an object.

Plugins allow you to customise Rollup's behaviour by, for example, transpiling code before bundling, or finding third-party modules in your node_modules folder. For an example on how to use them, see Using plugins.

A List of Plugins may be found at github.com/rollup/awesome. If you would like to make a suggestion for a plugin, please submit a Pull Request.

A Simple Example

The following plugin will intercept any imports of virtual-module without accessing the file system. This is for instance necessary if you want to use Rollup in a browser. It can even be used to replace entry points as shown in the example.

// @filename: rollup-plugin-my-example.js
export default function myExample
 () {
  return {
    name
: 'my-example', // this name will show up in logs and errors
    resolveId
 ( source
 ) {
      if (source
 === 'virtual-module') {
        // this signals that Rollup should not ask other plugins or check
        // the file system to find this id
        return source
;
      }
      return null; // other ids should be handled as usually
    },
    load
 ( id
 ) {
      if (id
 === 'virtual-module') {
        // the source code for "virtual-module"
        return 'export default "This is virtual!"';
      }
      return null; // other ids should be handled as usually
    }
  };
}

// @filename: rollup.config.js
import myExample
 from './rollup-plugin-my-example.js';
export default ({
  input
: 'virtual-module', // resolved by our plugin
  plugins
: [myExample
()],
  output
: [{
    file
: 'bundle.js',
    format
: 'es'
  }]
});

Conventions

Plugins should have a clear name with rollup-plugin- prefix.
Include rollup-plugin keyword in package.json.
Plugins should be tested. We recommend mocha or ava which support Promises out of the box.
Use asynchronous methods when it is possible, e.g. fs.readFile instead of fs.readFileSync.
Document your plugin in English.
Make sure your plugin outputs correct source mappings if appropriate.
If your plugin uses 'virtual modules' (e.g. for helper functions), prefix the module ID with \0. This prevents other plugins from trying to process it.

Properties

name

Type:	`string`

The name of the plugin, for use in error messages and logs.

version

Type:	`string`

The version of the plugin, for use in inter-plugin communication scenarios.

Build Hooks

To interact with the build process, your plugin object includes "hooks". Hooks are functions which are called at various stages of the build. Hooks can affect how a build is run, provide information about a build, or modify a build once complete. There are different kinds of hooks:

async: The hook may also return a Promise resolving to the same type of value; otherwise, the hook is marked as sync.
first: If several plugins implement this hook, the hooks are run sequentially until a hook returns a value other than null or undefined.
sequential: If several plugins implement this hook, all of them will be run in the specified plugin order. If a hook is async, subsequent hooks of this kind will wait until the current hook is resolved.
parallel: If several plugins implement this hook, all of them will be run in the specified plugin order. If a hook is async, subsequent hooks of this kind will be run in parallel and not wait for the current hook.

Instead of a function, hooks can also be objects. In that case, the actual hook function (or value for banner/footer/intro/outro) must be specified as handler. This allows you to provide additional optional properties that change hook execution or skip hook execution:

order: "pre" | "post" | null
If there are several plugins implementing this hook, either run this plugin first ("pre"), last ("post"), or in the user-specified position (no value or null).
js
```
export default function resolveFirst
() {
	return {
		name
: 'resolve-first',
		resolveId
: {
			order
: 'pre',
			handler
(source
) {
				if (source
 === 'external') {
					return { id
: source
, external
: true };
				}
				return null;
			}
		}
	};
}
```
If several plugins use "pre" or "post", Rollup runs them in the user-specified order. This option can be used for all plugin hooks. For parallel hooks, it changes the order in which the synchronous part of the hook is run.
sequential: boolean
Do not run this hook in parallel with the same hook of other plugins. Can only be used for parallel hooks. Using this option will make Rollup await the results of all previous plugins, then execute the plugin hook, and then run the remaining plugins in parallel again. E.g. when you have plugins A, B, C, D, E that all implement the same parallel hook and the middle plugin C has sequential: true, then Rollup will first run A + B in parallel, then C on its own, then D + E in parallel.
This can be useful when you need to run several command line tools in different writeBundle hooks that depend on each other (note that if possible, it is recommended to add/remove files in the sequential generateBundle hook, though, which is faster, works with pure in-memory builds and permits other in-memory build plugins to see the files). You can combine this option with order for additional sorting.
js
```
import path
 from 'node:path';
import { readdir
 } from 'node:fs/promises';

export default function getFilesOnDisk
() {
	return {
		name
: 'getFilesOnDisk',
		writeBundle
: {
			sequential
: true,
			order
: 'post'
```

Plugin Development

Plugins Overview ​

A Simple Example ​

Conventions ​

Properties ​

name ​

version ​

Build Hooks ​