Skip to main content
This guide explains how to integrate Mellowtel into your browser extension without using bundlers like Webpack or Vite. Instead, you’ll use a single pre-bundled file that works in both content scripts and service workers.

​
Project Setup

Start with a basic browser extension structure: 
your-extension/
├── icons/
├── popup/
│   ├── popup.html
│   └── popup.js
├── background.js           # Your service worker
├── content_script.js
├── manifest.json
└── mellowtel.js           # Will be added in next step

​
Getting the Mellowtel Bundle

You have two options to get the mellowtel.js file for your extension:

​
Option 1: Use Pre-bundled File

The easiest way to get started is to use the pre-bundled mellowtel.js file from the mellowtel-bundled repository.
  1. Go to the mellowtel-bundled repository
  2. Download the mellowtel.js file
  3. Copy it to your extension directory

​
Option 2: Generate Your Own Bundle

If you prefer to generate the bundle yourself, follow these steps:

​
Create a Temporary Bundling Directory

Create a temporary directory to install Mellowtel and generate the bundle: 
mkdir mellowtel-bundling
cd mellowtel-bundling
npm init -y
npm install mellowtel
This creates a separate folder with the Mellowtel package that you’ll use only for bundling.

​
Bundle Mellowtel with esbuild

From inside the mellowtel-bundling directory, create a single bundle that works in both service workers and content scripts: 
npx esbuild node_modules/mellowtel/dist/index.js --bundle --format=iife --global-name=Mellowtel --footer:js="globalThis.Mellowtel = Mellowtel.default" --platform=browser --outfile=mellowtel.js --minify --legal-comments=none
This command:
  • Takes the Mellowtel source from node_modules/mellowtel/dist/index.js
  • Bundles all dependencies into a single file
  • Uses IIFE format with a global name for universal compatibility
  • Adds a footer to make the default export available globally
  • Optimizes for browser environment and minifies the output
  • Creates mellowtel.js in the bundling directory

​
Copy the Bundle to Your Extension

After running the esbuild command, copy the generated file to your extension directory: 
cp mellowtel.js ../your-extension/
Now you can delete the temporary bundling directory since you only needed the output file: 
cd ..
rm -rf mellowtel-bundling
Your extension folder now contains the bundled Mellowtel file ready to use.

​
Configure Your Manifest (Both Options)

Regardless of which option you chose above, configure your manifest.json to include the Mellowtel bundle in content scripts: 
{
  "manifest_version": 3,
  "name": "Your Extension Name",
  "version": "1.0",
  "background": {
    "service_worker": "background.js",
    "type": "module"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["mellowtel.js", "content_script.js"]
    }
  ],
  "permissions": [
    "storage",
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "\u003Call_urls\u003E"
  ]
}
Important:
  • The "type": "module" field enables ES module imports in your service worker.
  • In the content scripts array, mellowtel.js must be loaded before content_script.js so that the Mellowtel global variable is available when your content script runs.

​
Use Mellowtel in Your Extension

For your service worker (background.js), import the bundled file: 
// background.js
import './mellowtel.js';

(async () => {
    const mellowtel = new Mellowtel("<configuration_key>"); // Replace with your configuration key
    await mellowtel.initBackground();
})();
For content scripts, Mellowtel is available as a global variable (no import needed, as it’s loaded via the manifest): 
// content_script.js
// Mellowtel is available as a global variable from mellowtel.js

(async () => {
  const mellowtel = new Mellowtel("<configuration_key>"); // Replace with your configuration key
  await mellowtel.initContentScript();
})();

​
Testing Your Extension

To test your extension:
  1. Go to chrome://extensions/ in Chrome (or equivalent in other browsers)
  2. Enable “Developer mode”
  3. Click “Load unpacked” and select your extension folder
This approach gives you the benefits of using Mellowtel without the complexity of setting up a full build system like Webpack or Vite.
⌘I