Create Browser Extension with Vite + TS

Let's begin this exercise focusing on setting up the most basic extension structure, one that includes just a manifest file and a service worker. The manifest acts as the configuration file, specifying what the extension is allowed to do, while the service worker handles background tasks, primarily responding to browser events, in this instance, it logs when the extension is installed.

{
  "name": "Simple",
  "version": "0.0.1",
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  }
}

manifest.json

console.log("Initialized background script!");

chrome.runtime.onInstalled.addListener((object) => {
  console.log("Installed background script!");
});

background.js

The service worker can be as complex as needed, but we'll keep it straightforward for now as the goal of this task is to transform this simple two-file extension into a Vite project.

So why use Vite? Primarily because I've decided to work with TypeScript, which will significantly improve code quality, maintainability, and productivity. Beyond offering self-documentation, TypeScript allows me to catch type-related errors at compile-time rather than at runtime, enhancing the overall development experience.

Vite

Although a Node project with TypeScript would suffice to compile my TS code into the vanilla JavaScript required by my extension, I opted for Vite. Vite, especially with its Rollup bundler, offers extensive capabilities like tree-shaking and bundle minification. Additionally, Vite’s robust plugin ecosystem would allow me to easily integrate React if I decide to create UI components for the extension in the future.

With that in mind, let’s start by creating the Vite project using its vanilla-ts template.

npm create vite@latest simple-extension -- --template vanilla-ts

After running the command and installing dependencies, you’ll have a small web project set up with TypeScript. However, since this setup isn’t quite what we need, we’ll start with some cleanup. First, delete the index.html file from the root folder, as it’s not required anymore. Then, remove all files in the src folder except for vite-env.d.ts, which provides type definitions for Vite-specific features. Finally, delete everything in the public folder.

⚠️ If you encounter errors in your tsconfig file about unknown compiler options, ensure that your editor is using the same TypeScript version installed for the project.

Next, create a new file in the src folder named background.ts and copy the code from the original background.js file into it.

You’ll soon notice that TypeScript requires additional context to function properly, as it doesn’t recognize the chrome object without the appropriate types. To address this, install @types/chrome to provide the necessary type definitions for chrome.

npm i -D @types/chrome

Once installed, the TypeScript errors disappear. However, you may notice a warning message in the onInstalled callback. This is due to the linting properties that Vite has configured for us in our TypeScript setup.

/* Linting */
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noUncheckedSideEffectImports": true

tsconfig.json

Since we’re defining an object that isn’t used, let’s go ahead and remove it. That should be all we need, so now we can compile the project.

npm run build

There seems to be an issue—the default Vite configuration is still attempting to use some of the files we just removed as the code entry point.

x Build failed in 6ms
error during build:
Could not resolve entry module "index.html".

We need to customize our Vite configuration to run in Library Mode. Here’s the minimal configuration required for this project.

import { defineConfig } from "vite";

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        background: "./src/background.ts",
      },
      output: {
        entryFileNames: `[name].js`,
      },
    },
  },
});

vite.config.ts

In the configuration above, we’re simply setting the project’s input to ./src/background.ts and adjusting the output filename to [name].js. By default, Vite appends a hash to filenames for production builds (e.g., background-[hash].js), but we need an exact filename match for our manifest.json to work correctly.

Speaking of manifest.json, where should it be located? This part is straightforward: any file that should be copied as-is, without transformations, to the output folder should be placed in the public folder. Now, if we build the project again, we’ll find our two-file browser extension compiled in the dist folder.

npm run build

Installation

Let’s now verify everything is working as expected. If you haven’t tested a browser extension locally before, just follow these simple steps:

1. Open the Extensions page by entering chrome://extensions in a new tab.
2. Enable Developer Mode by toggling the Developer mode switch.
3. Click Load unpacked and select the extension directory, which is the dist folder generated by Vite. And that’s it! The extension is now installed. If you click on the service worker link, the DevTools for this service worker will open, where you can view the logs generated by our worker in action.

simple-vite-extension