rollup-plugin-chrome-extension: A TypeScript repository from witcher-development

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.json

import { rollup } from 'rollup'

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

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

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

Add these scripts to your project.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've included the helper plugin pushReloader in your config,when Rollup is in watch mode the it will include an auto-reloader script. This feature will reload your extension every time Rollup produces a new build. You should know that pushReloader connects to Firebase to do its magic. Get the details here. The only time you may need to manually reload is when you first start a watch session.

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

Automatic Reloaders

TLDR; The pushReloader plugin creates system notifications to let you know when the extension will reload. It uses Firebase and creates an anonymous account to associate installs with the Rollup watch session. We don't keep any data about you after you exit Rollup.

Make sure you do a production build before releasing to the Chrome Web Store! The reloader won't hurt anything, but there's no reason to include it.

There are two reloaders to choose from: a Push notification reloader that is compatible with non-persistent background ~~Event~~ pages, or a simple reloader that makes the background page persistent.

You should know that the Push reloader uses Firebase Cloud Messaging to tell the extension when to reload. It creates an anonymous account for each Rollup watch session, which is deleted when Rollup exits that watch session. This is necessary to associate the extension installation with the watch session.

If you're not comfortable with anonymous accounts, or need to develop without an internet connection, you can use the simple reloader. It just checks a timestamp file periodically. It also works between watch sessions.

witcher-development/rollup-plugin-chrome-extension