rollup-plugin-chrome-extension: A TypeScript repository from jones-sam

rollup-plugin-chrome-extension

A feature-rich solution for bundled Chrome extensions! 💯

Build Chrome extensions using Rollup, with minimal configuration.

Use manifest.json as the input. Every file in the manifest will be bundled or copied to the output folder.

Getting Started
Usage
Features
API Documentation

Getting started

Installation

$ npm i rollup rollup-plugin-chrome-extension@latest -D

Install the plugins Node Resolve and CommonJS if you plan to use npm modules.

$ npm i @rollup/plugin-node-resolve @rollup/plugin-commonjs -D

Usage

Create a rollup.config.js file in your project root.

// rollup.config.js

import resolve from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'

import {
  chromeExtension,
  simpleReloader,
} from 'rollup-plugin-chrome-extension'

export default {
  input: 'src/manifest.json',
  output: {
    dir: 'dist',
    format: 'esm',
  },
  plugins: [
    // always put chromeExtension() before other plugins
    chromeExtension(),
    simpleReloader(),
    // the plugins below are optional
    resolve(),
    commonjs(),
  ],
}

Add these scripts to your package.json file.

// package.json

{
  "scripts": {
    "build": "rollup -c",
    "watch": "rollup -c -w"
  }
}

Put your Chrome extension source code in a folder named src in the root of your project and build with the following command:

$ npm run build

Your extension build will be in the dist folder. It has everything it needs: manifest, scripts, and assets (images, css, etc...).

Install it in Chrome to test drive your extension! 🚗

Features

Worry Less About Your Manifest

rollup-plugin-chrome-extension validates your output manifest, so you discover mistakes when you build, not in a cryptic Chrome alert later.

You can omit manifest_version, version, name, and description from your source manifest.json. We'll fill them out automatically from your package.json, if you use an npm script to run Rollup. Just manage your version number in package.json and it will reflect in your extension build.

Don't worry, any value in your source manifest will override that value from package.json! 😉

Reload Your Extension Automatically

Reloading your Chrome extension every time you change your code can be a pain, and if you forget to reload, you're left wondering, "Why isn't this working?"

If you include the helper plugin simpleReloader in your config, when Rollup is in watch mode your background page will include an auto-reloader script. This will reload your extension every time Rollup produces a new build.

Ever got the error "Extension context invalidated" in your content script? That happens when the extension reloads but the content script doesn't. Our reloader makes sure that doesn't happen by reloading your content scripts when it reloads your extension.

Write Chrome Extensions In TypeScript

If you use @rollup/plugin-typescript in your plugins, you can write your Chrome extension in TypeScript. That's right, the scripts in your manifest and in your HTML script tags.

TypeScript definitions are included, so no need to install an additional @types library!

Manage Your Assets With Ease

Your manifest.json doesn't only contain script files. There are images, icons, and even CSS files. We've got you covered. These assets are automatically copied into the output folder. Even the images in your HTML files get copied over.

Bundle Everything In Your HTML Files

What about your Options and Popup pages? rollup-plugin-chrome-extension uses the JS or even TS files in your HTML files as entry points. Shared code is split out into chunks automatically, so libraries like React and Lodash aren't bundled into your extension multiple times.

Derive Permissions Automatically

rollup-plugin-chrome-extension statically analyzes your bundled code to detect required permissions to declare in the manifest. Any permissions in the source manifest are always included.

Use ES2015 Modules In Your Scripts

Chrome extensions don't support modules in background and content scripts. We've developed a module loader specifically for Chrome extension scripts, so you can take advantage of Rollup's great code splitting features.

Plugins Take It To The Next Level

Take advantage of other great Rollup plugins to do awesome things with your Chrome extensions!

Some of our favorites are:

Write your extension in TS with @rollup/plugin-typescript
Import CSS in JS files with rollup-plugin-postcss
Zip your extension when you build with rollup-plugin-zip.

Two of our own plugins:

Import a module as a string of code to use in chrome.runtime.executeScript with rollup-plugin-bundle-imports
Empty your output folder before a new build with rollup-plugin-empty-dir

jones-sam/rollup-plugin-chrome-extension