Skip to main content
The build system compiles the extension for both Chrome and Firefox browsers using Manifest V3.

​
Prerequisites

Ensure you have Node.js 22 or higher installed: 
node --version

​
Build Scripts

The extension provides several build commands for different scenarios:

​
Build for Specific Browser

npm run build:chrome
These commands build the extension for a specific browser and output to dist/chrome/ or dist/firefox/.

​
Build for All Browsers

npm run build:all
Builds for both Chrome and Firefox sequentially. This is equivalent to running: 
npm run build:chrome && npm run build:firefox

​
Generic Build

npm run build
The base build command builds for all browsers by default.

​
Watch Mode for Development

During development, use watch mode to automatically rebuild when source files change: 
npm run dev:chrome
Watch mode uses chokidar to monitor the src/ directory and triggers a rebuild on any file changes.

​
Build Process

The build script (scripts/build.js) performs the following steps:
1

Clean the distribution directory

Empties the target dist/{browser}/ directory to ensure a fresh build
2

Copy source files

Copies the following directories to the distribution folder:
  • popup/ - Extension popup UI
  • options/ - Settings page
  • content/ - Content scripts
  • background/ - Service worker
  • lib/ - Shared utilities
  • assets/ - Icons and images
3

Merge manifests

Combines manifest/base.json with browser-specific manifest (manifest/chrome.json or manifest/firefox.json) using deep merge
4

Write final manifest

Outputs the merged manifest.json to the distribution directory

​
Deep Merge Strategy

The build process uses deep merging to combine manifests: 
// Base manifest (shared config)
{
  "manifest_version": 3,
  "name": "FreshJuice HubSpot DevTools",
  "permissions": ["storage", "activeTab"]
}

// Chrome-specific overrides
{
  "background": {
    "service_worker": "background/background.js"
  }
}

// Firefox-specific overrides
{
  "background": {
    "scripts": ["background/background.js"]
  },
  "browser_specific_settings": {
    "gecko": { "id": "extension@freshjuice.dev" }
  }
}

​
Creating Release Zips

To package the extension for distribution: 
# Chrome
npm run zip:chrome

# Firefox
npm run zip:firefox
Zip files are created with the naming convention: hubspot-devtools-{browser}-{version}.zip

​
Complete Release Build

For a production release, use the release command: 
npm run release
This command executes the following workflow:
1

Clean previous builds

npm run clean
Removes the entire dist/ directory
2

Run validation

npm run validate
Runs linting, tests, and browser-specific validations
3

Build all browsers

npm run build:all
Creates distribution builds for Chrome and Firefox
4

Create zip archives

npm run zip:all
Packages both browsers into zip files ready for upload to stores

​
Output Structure

After building, your dist/ directory will look like: 
dist/
├── chrome/
│   ├── manifest.json
│   ├── popup/
│   ├── options/
│   ├── background/
│   ├── content/
│   ├── lib/
│   └── assets/
└── firefox/
    ├── manifest.json
    ├── popup/
    ├── options/
    ├── background/
    ├── content/
    ├── lib/
    └── assets/

​
Manual Installation for Testing

​
Chrome

1

Build the extension

npm run build:chrome
2

Open Chrome extensions

Navigate to chrome://extensions/
3

Enable Developer mode

Toggle the “Developer mode” switch in the top right
4

Load unpacked extension

Click “Load unpacked” and select the dist/chrome/ directory

​
Firefox

1

Build the extension

npm run build:firefox
2

Open Firefox debugging

Navigate to about:debugging#/runtime/this-firefox
3

Load temporary add-on

Click “Load Temporary Add-on” and select any file in dist/firefox/ (e.g., manifest.json)

​
Troubleshooting

​
Build Fails

If the build fails, check:
  • Node.js version is 22 or higher
  • Dependencies are installed: npm install
  • No syntax errors in source files

​
Manifest Errors

If you see manifest validation errors:
  • Verify manifest/base.json has valid JSON
  • Check browser-specific manifests for conflicts
  • Run validation: npm run validate:chrome or npm run validate:firefox

​
Watch Mode Not Triggering

If watch mode doesn’t rebuild on changes:
  • Ensure you’re editing files in the src/ directory
  • Check that the file isn’t in node_modules/
  • Restart watch mode with Ctrl+C and run again

Build docs developers (and LLMs) love

Get started for freeTalk to us