Forem: Jack Steam

RPCE is moving Vite support to @crxjs/vite-plugin

Jack Steam — Fri, 29 Apr 2022 16:28:10 +0000

tldr;

Since RPCE is no longer a Rollup plugin, it's getting a new name: @crxjs/vite-plugin.

If you are using rollup-plugin-chrome-extension with Vite, you can migrate your existing project using this codemod:

npx @crxjs/migrate

If you're already using @crxjs/vite-plugin, you don't need to read this article.

RPCE is growing up

There's still a lot to do in terms of features and robustness, but the initial feature set is complete:

HMR for React and Vue in extension pages and content scripts
No-config dynamic content scripts
Vite-style static asset imports in content scripts

Thank you to every developer who took the time to test Vite support in RPCE and create an issue. Building Chrome Extensions isn't easy! Your time and patience are vital in building a better DX for Chrome Extensions.

RPCE gets a new name

My original plan was to make an actual Rollup plugin that supported Vite and Rollup. Unfortunately, that turned out to be a monumental task. Every feature and use case increases the complexity of a project, and RPCE was no exception. I finally had to compromise and remove Rollup support to progress towards the Vite-style experience we wanted.

That leaves us with a small problem. rollup-plugin-chrome-extension isn't a Rollup plugin, so we're taking the opportunity to rebrand to @crxjs/vite-plugin.

Migration instructions

I've published a codemod to make it easy to migrate. Execute this package in your project root folder:

npx @crxjs/migrate

The script will ask if you want to remove rollup-plugin-chrome-extension, then it will install @crxjs/vite-plugin and replace the import name in your Vite config.

OFC, you can do this yourself:

npm rm rollup-plugin-chrome-extension
npm i -D @crxjs/vite-plugin

// vite.config.js

-- import { chromeExtension } from 'rollup-plugin-chrome-extension'
++ import { crx } from '@crxjs/vite-plugin'
import manifest from './manifest.json'

export default {
--  plugins: [chromeExtension({ manifest })]
++  plugins: [crx({ manifest })]
}

The plugin API options will remain the same. The export crx is just an alias for chromeExtension. You can import either chromeExtension or crx, but I will use crx in future examples for brevity.

Contributing

Thanks for giving RPCE a try while it was still in beta! In the coming months, you can look forward to better docs, better Vue support, and even Svelte support.

If this plugin is valuable to you or your business, please consider sponsoring me on GitHub. Chrome Extensions are an evolving and poorly understood space in the web development world, and I'd like to continue improving your developer experience. Your contributions and sponsorship will go a long way to making this happen.

Here's our new logo!

Advanced Config for CRXJS Vite Plugin

Jack Steam — Tue, 12 Apr 2022 21:17:53 +0000

The CRXJS Vite plugin has been in beta long enough to get a good sample of developer use cases. Thanks to everyone who has helped by creating issues and participating in discussions! Your input is super valuable.

These are some answers to the most common developer questions we've fielded. I'm Jack Steam, creator of CRXJS. So, if you're looking to add extra HTML pages, extend the manifest at build time, use the new Chrome Scripting API, and inject main world scripts, read on!

Extra HTML pages
Dynamic manifest with TypeScript
Manifest icons and public assets
Web accessible resources
Dynamic content scripts
Injected main world scripts

Extra HTML pages

It's pretty common for an extension to have web pages that you can't declare in the manifest. For example, you might want to change the popup once the user signs in or open a welcome page when the user installs the extension. In addition, devtool extensions like React Developer Tools don't declare their inspector panels in the manifest.

Given the following file structure and manifest, index.html and src/panel.html will be available during development but not in a production build. We can fix this in vite.config.ts.

.
├── vite.config.ts
├── manifest.json
├── index.html
└── src/
    ├── devtools.html
    └── panel.html

// manifest.json
{
  "manifest_version": 3,
  "version": "1.0.0",
  "name": "example",
  "devtools_page": "src/devtools.html"
}

To build extra HTML pages, follow the pattern from the Vite Documentation for Multi-Page Apps:

// vite.config.js
import { resolve } from 'path';
import { defineConfig } from 'vite';
import { crx } from '@crxjs/vite-plugin';
import manifest from './manifest.json';

export default defineConfig({
  build: {
    rollupOptions: {
      // add any html pages here
      input: {
        // output file at '/index.html'
        welcome: resolve(__dirname, 'index.html'),
        // output file at '/src/panel.html'
        panel: resolve(__dirname, 'src/panel.html'),
      },
    },
  },
  plugins: [crx({ manifest })],  
});

Dynamic manifest with TypeScript

CRXJS treats the manifest as a config option and transforms it during the build process. Furthermore, since the manifest is a JavaScript Object, it opens up some exciting ways to extend it.

Imagine writing your manifest in TypeScript. Use different names for development and production. Keep the version number in sync with package.json. 🤔

The Vite plugin provides a defineManifest function that works like Vite's defineConfig function and provides IntelliSense, making it easy to extend your manifest at build time.

// manifest.config.ts

import { defineManifest } from '@crxjs/vite-plugin'
import { version } from './package.json'

const names = {
  build: 'My Extension',
  serve: '[INTERNAL] My Extension'
}

// import to `vite.config.ts`
export default defineManifest((config, env) => ({
  manifest_version: 3,
  name: names[env.command],
  version,
}))

Manifest icons and public assets

If you've used Vite for a website, you might be familiar with the public directory. Vite copies the contents of public to the output directory.

You can refer to public files in the manifest. If CRXJS doesn't find a matching file in public, it will look for the file relative to the Vite project root and add the asset to the output files.

You're free to put your icons in public or anywhere else that makes sense!

// manifest.json 
{
  "icons": {
    // from src/icons/icon-16.png
    "16": "src/icons/icon-16.png",
    // from public/icons/icon-24.png 
    "24": "icons/icon-24.png"
  },
  "web_accessible_resources": [{
    matches: ['https://www.google.com/*'],
    // copies all png files in src/images
    resources: ["src/images/*.png"]
  }]
}

The plugin will also copy files that match globs in web_accessible_resources.

CRXJS ignores the globs * and **/*. You probably don't want to copy package.json and everything in node_modules. The real question is, should a website have access to every single file in your extension?

What are web-accessible resources, anyways?

Web Accessible Resources

The files in your Chrome Extension are private by default. So, for example, if your extension has the file icon.png, extension pages can access it, but random websites cannot (it's not a web-accessible resource). If you want an extension resource to be web-accessible, you need to declare the file in the manifest under web_accessible_resources.

What if I want to use an image in a content script? It has to be web-accessible. Why? Content scripts share the origin of the host page, so a web request from a content script on https://www.google.com is the same as a request from https://www.google.com itself.

It can get tedious to update the manifest with every file you're using. We're using build tools, so why do more manual work than necessary? When you import an image into a content script, CRXJS updates the manifest automatically. ✨

All you need to do is wrap the import path with a call to chrome.runtime.getURL to generate the extension URL:

import logoPath from './logo.png'

const logo = document.createElement('img')
logo.src = chrome.runtime.getURL(logo)

These files are accessible anywhere the content script runs. Also, these assets use a dynamic url, so malicious websites can't use it to fingerprint your extension!

Dynamic Content Scripts

The Chrome Scripting API lets you execute content scripts from the background of a Chrome Extension.

The manifest doesn't have a place to declare dynamic content scripts, so how do we tell Vite about them? Of course, we could add them to the Vite config like an extra HTML page, but how does CRXJS know that we intend the added script to be a content script? Does it need the unique flavor of HMR that CRXJS provides? What about web-accessible resources?

CRXJS uses a unique import query to designate that an import points to a content script. When an import name ends with the query ?script, the default export is the output filename of the content script. You can then use this filename with the Chrome Scripting API to execute that content script and profit from Vite HMR.

import scriptPath from './content-script?script'

chrome.action.onClicked.addListener((tab) => {  
  chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: [scriptPath]
  });
});

The resources of a dynamic content script are available to all URLs by default, but you can tighten that up using the defineDynamicResource function:

import { defineManifest, defineDynamicResource } from '@crxjs/vite-plugin'

export default defineManifest({
  ...manifest,
  web_accessible_resources: [
    defineDynamicResource({
      matches: ['https://www.google.com/*'],
    })
  ]
})

Main world scripts

Content scripts run in an isolated world, but sometimes a script needs to modify the execution environment of the host page. Content scripts usually do this by adding a script tag to the DOM of their host page. The main world script must be web-accessible like any other content script asset.

A dynamic content script import gets us close, but a script imported using ?script includes a loader file that adds Vite HMR. Unfortunately, the loader relies on the Chrome API only available to content scripts; it won't work in the host page execution environment. What we need is a simple ES module.

You can skip the loader file using the ?script&module import query:

// content-script.ts
import mainWorld from './main-world?script&module'

const script = document.createElement('script')
script.src = chrome.runtime.getURL(mainWorld)
script.type = 'module'
document.head.prepend(script)

Now get out there and read global variables, reroute fetch requests, and decorate class prototypes to your heart's content!

Roadmap

The next thing on CRXJS's roadmap is proper documentation and a better release process. But, don't worry, we're not done adding features and fixing bugs; you can look forward to Shadow DOM in content scripts and better Vue support. I'm also incredibly excited about adding official support for Svelte and Tailwind!

If CRXJS has improved your developer experience, please consider sponsoring me on GitHub or give me a shoutout on Twitter. See you next time.

Real Vite-React HMR in Chrome Extension Content Scripts

Jack Steam — Fri, 18 Mar 2022 20:26:00 +0000

A content script is JavaScript from a Chrome Extension that the browser executes on a designated host page. It shares the DOM with the host page but has a separate JavaScript environment.

If you've done any work on Chrome Extensions, you know that content scripts are one of the essential tools at your disposal. However, you also know they are a PITA to develop.

The traditional content script developer experience is as follows:

Make changes to your code
Reload the extension in chrome://extensions
Reload the host page
Check that things work right
Repeat

Forget a step, and your changes don't show up. Hopefully, you realize what's happening before you start debugging. 😅

Adding DOM elements to a website is a standard content script use case. Unfortunately, you need to bundle your code to use a framework like React or Vue in a content script.

Vite does a great job serving code for the browser, but content scripts load their code from the file system, so Vite's sweet HMR experience doesn't work out of the box. Until now.

Good News for Content Script DX

You can have HMR in content scripts; you can say goodbye to the tedious workflow they represent. My name is Jack Steam, and I'm the creator of the CRXJS Vite plugin. Today CRXJS brings an authentic Vite HMR experience to content scripts for the first time. Let me show you how to get started.

If you're coming from my first article, Create a Vite-React Chrome Extension in 90 seconds, you already know how to get started; you can skip this next bit. Instead, scroll down to the next heading, "Add a content script".

Getting Started

Using your favorite package manager, initialize a new Vite project. Follow the prompts to set up your project. CRXJS works with React and Vue, but we'll use React for this guide.

CRXJS doesn't yet work with Vite 3, but support is coming soon.

npm init vite@^2
cd <your-project-name>
npm install
npm i @crxjs/vite-plugin@latest -D

Open vite.config.js and add CRXJS:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
+ import { crx } from '@crxjs/vite-plugin'

export default defineConfig({
- plugins: [react()]
+ plugins: [react(), crx()]
})

Chrome Extensions declare their resources using a manifest.json file. Create your manifest next to vite.config.js with these fields:

{
  "manifest_version": 3,
  "name": "Vite React Chrome Extension",
  "version": "1.0.0"
}

Go back to vite.config.js and add the manifest:

// other imports...
+ import manifest from './manifest.json'

export default defineConfig({
- plugins: [react(), crx()]
+ plugins: [react(), crx({ manifest })]
})

Add a content script

We declare content scripts with a list of JavaScript files and match patterns for the pages where Chrome should execute our content script. In manifest.json, create the field content_scripts with an array of objects:

{
  // other fields...
  "content_scripts": [{
    "js": ["src/main.jsx"],
    "matches": ["https://www.google.com/*"]
  }]
}

Here we're telling Chrome to execute src/main.jsx on all pages that start with https://www.google.com.

Create the root element

Content scripts don't use an HTML file, so we need to create our root element and append it to the DOM before mounting our React app. Open src/main.jsx and add a root element.

import React from 'react'
import ReactDOM from 'react-dom'
import './index.css'
import App from './App'

+ const root = document.createElement('div')
+ root.id = 'crx-root'
+ document.body.append(root)

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
- document.getElementById('root')
+ root
)

Get the right URL

Content scripts share the origin of their host page. We need to get a URL with our extension id for static assets like images. Let's go to src/App.jsx and do that now.

<img
- src={logo}
+ src={chrome.runtime.getURL(logo)}
  className="App-logo"
  alt="logo"
/>

Now our content script is ready for action! But, first, let's load our extension in Chrome.

Load the extension

Start Vite in the terminal.

npm run dev

Open the extensions dashboard at the URL chrome://extensions and turn on development mode using the switch in the top right corner. Next, load your extension by dragging the dist folder onto the extensions dashboard.

Profit with HMR

Navigate to https://www.google.com and scroll to the bottom of the page. There's our familiar Vite Hello World!

Notice how the counter button doesn't look like a button. That's because Google's styles affect our content script elements. The same goes the other way: our styles change Google's styles.

Let's fix that. Replace everything in src/index.css with this:

#crx-root {
  position: fixed;
  top: 3rem;
  left: 50%;
  transform: translate(-50%, 0);
}

#crx-root button {
  background-color: rgb(239, 239, 239);
  border-color: rgb(118, 118, 118);
  border-image: initial;
  border-style: outset;
  border-width: 2px;
  margin: 0;
  padding: 1px 6px;
}

CRXJS will quickly rebuild the content script, and our CSS changes will take effect. Now our div position is fixed, and that button looks more like a button! Click the count button and play around with src/App.jsx to see Vite HMR at work.

We need your feedback! If something doesn't work for you, please create an issue.

Conversely, if CRXJS has improved your developer experience, please consider sponsoring me on GitHub or give me a shoutout on Twitter. See you next time.

Good luck building your Chrome Extension!

Create a Vite-React Chrome Extension in 90 seconds

Jack Steam — Wed, 15 Dec 2021 22:41:00 +0000

The bundler configuration for a Chrome Extension can be pretty complex. When I started making Chrome Extensions, they were small projects for clients who wanted to automate a task. I was starting a new Chrome Extension almost every week, and it took too much time to configure a new project. Then I thought, "We already have a manifest; why do we need more config files?"

That's the idea behind CRXJS Vite Plugin. My name is Jack Steam, and I've been hard at work over the creating a Vite plugin for Chrome Extensions. So today, I'm excited to invite you to try out CRXJS with Vite.

CRXJS makes it easy to set up a Chrome Extension project with a modern development experience. How easy? Let me show you.

Create your project

Use your favorite package manager to scaffold a new project and follow the prompts to create a React project.

CRXJS doesn't yet work with Vite 3, but support is coming soon!

npm init vite@^2

Install CRXJS Vite Plugin

Now install the latest release of CRXJS using your favorite package manager.

npm i @crxjs/vite-plugin -D

Update the Vite config

Update vite.config.js to match the code below.

// vite.config.js

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { crx } from "@crxjs/vite-plugin";
// Node 14 & 16
import manifest from './manifest.json'
// Node >=17
import manifest from './manifest.json' assert { type: 'json' } 

export default defineConfig({
  plugins: [react(), crx({ manifest })],
});

Create a file named manifest.json next to vite.config.js.

// manifest.json
{
  "manifest_version": 3,
  "name": "CRXJS React Vite Example",
  "version": "1.0.0",
  "action": { "default_popup": "index.html" }
}

And run the dev command.

npm run dev

That's it! CRXJS will do the rest. Your project directory should look like this:

Add the extension to Chrome

Let's try it out.

When the build completes, open Chrome or Edge and navigate to chrome://extensions. Make sure to turn on the developer mode switch.

Chrome	Edge
Top right corner	Middle left sidebar

Drag your dist folder into the Extensions Dashboard to install it. Your extension icon will be in the top bar. The icon will be the first letter of the extension's name.

Profit with Vite HMR

Once you've found the extension icon, right-click it and choose "Inspect popup window". This will open the popup and the popup dev tools window. We need to inspect the popup to keep it open while making changes.

That popup is pretty tiny; let's add some CSS to make it wider.

/* App.css */
.App {
  text-align: center;
+ min-width: 350px;
}

And boom! HMR magic at work.

If you enjoyed this how-to guide, check out CRXJS on GitHub and give us a star!