Chrome Extension Development Setup: Tooling, Hot Reload and Testing

What do you need to start Chrome extension development?

You need Chrome, a code editor, Node.js and a manifest.json file. Nothing else is required to run an extension, because Chrome loads plain HTML, CSS and JavaScript directly from a folder.

Modern extensions use Manifest V3. The manifest declares the extension name, version, permissions and entry points: a background service worker, content scripts that run inside web pages, and UI pieces such as the popup, options page and side panel.

A minimal project is only a folder with three files. That is worth building once by hand before you pick a framework, because it shows you what the frameworks generate for you.

{
  "manifest_version": 3,
  "name": "Hello Extension",
  "version": "0.1.0",
  "action": { "default_popup": "popup.html" },
  "background": { "service_worker": "background.js" },
  "content_scripts": [
    { "matches": ["https://example.com/*"], "js": ["content.js"] }
  ],
  "permissions": ["storage"]
}

Keep permissions narrow from day one. Every host pattern and permission you add appears in the install warning, and reviewers and users both read it. Our permissions guide shows how those warnings look to a visitor.

How do you load and reload an extension while developing?

Turn on Developer mode at chrome://extensions, click Load unpacked and pick your project folder. Chrome installs it immediately and keeps reading from that folder.

1. Open chrome://extensions in Chrome. If you need a refresher, see our guide to enabling Developer mode in Chrome.
2. Switch on Developer mode in the top-right corner.
3. Click Load unpacked and select the folder that contains manifest.json (or your build output folder, such as dist or .output/chrome-mv3).
4. Pin the extension from the puzzle-piece menu in the toolbar so its icon stays visible.
5. After you change code, click the circular Reload arrow on the extension card, then refresh any page where a content script runs.

Chrome shows an Errors button on the card when it finds problems, such as a bad manifest key or an uncaught exception. Read it first, because many failures are manifest typos.

Content scripts only attach to pages loaded after the extension is (re)loaded. If your change seems to do nothing, refresh the tab. That single step explains most where-did-my-change-go questions.

Should you use WXT, Plasmo or plain Vite?

Use a framework once your extension has more than one entry point or needs TypeScript. WXT and Plasmo are the two common choices, and a Vite-based setup with a plugin such as CRXJS is the lighter alternative.

All of them solve the same chores: bundling each entry point, generating the manifest, hot reload while you edit, and packaging a zip for the store. They differ mainly in how much they decide for you. Check each project's own documentation for current features, since these tools change quickly.

If you are unsure, pick WXT or plain Vite for control and Plasmo for speed on a React project. Whichever you choose, keep business logic in plain modules that do not import browser APIs, so you can unit-test it without a browser.

How do you get hot reload for a Chrome extension?

Run your framework's dev command, which builds the extension into a folder and reloads it for you when files change. In WXT that is npm run dev, and in Plasmo it is also a dev script, and both usually open a Chrome window with the extension already loaded.

The reload behaviour differs by entry point. Popup and options pages can update in place. Content scripts typically reload and may need a page refresh. Changes to the manifest or the service worker often trigger a full extension reload, which briefly resets its state.

• Popup, options and side panel: update quickly, because they are ordinary pages.
• Content scripts: reinject on change, and some setups refresh the matching tab for you.
• Service worker: restarts on reload. Do not store state in globals; use chrome.storage instead.
• Manifest changes: need a full reload of the extension, and permission changes may prompt again.

If hot reload stops working, check the terminal first for build errors, then open the extension's card in chrome://extensions and press Reload once by hand. A stale service worker or a crashed dev server are the usual causes.

Keeping a tab auto-refreshing during content-script work also saves clicks. Tools such as Tab Auto Refresh and Tab Reloader reload pages on a timer, which helps when you test scripts against pages that update on their own.

How do you debug each part of an extension?

Each part has its own DevTools window, and opening the wrong one is the most common debugging mistake. Console output from a content script appears in the page's DevTools, not in the extension's.

Service worker

On chrome://extensions, click the service worker link on the extension card to open its DevTools. Logs, breakpoints and network requests from background code appear there.

Popup

Right-click the extension icon and choose Inspect popup. The popup closes when it loses focus, so keep DevTools open while you work.

Content script

Open DevTools on the page, go to the Sources panel and find your script under the extension's entry in the content scripts area. Use the context selector in the Console to run code in the extension's isolated world.

Options page and side panel

Right-click inside the page and choose Inspect, as with any web page.

Use chrome.storage for state and check it in the Application panel of the relevant DevTools. Many bugs that look like broken messaging are actually a service worker that went idle and lost its variables.

Cookie problems are another common time sink when your extension deals with logins. Extensions such as Cookie-Editor let you inspect and edit a site's cookies while you reproduce the bug.

Which Chrome extensions help with web and extension development?

The most useful ones inspect what a page is doing or speed up repetitive checks. These fit the developer workflow described above, and each has a catch you should know about.

See the wider set in the developer tools category or the extensions for developers page. Install these in your development profile only, since each one adds another set of permissions to the browser you test in.

How do you test a Chrome extension?

Test in two layers: unit tests for logic, and end-to-end tests that load the built extension into a real Chromium browser. The first runs in seconds; the second proves the manifest, permissions and content scripts really work.

For unit tests, use a runner such as Vitest or Jest, and mock the chrome API at the edge. Keep parsing, formatting and decision logic in modules that never touch chrome.*, so you rarely need mocks at all.

For end-to-end tests, Playwright and Puppeteer can launch Chromium with your extension. With Playwright you use a persistent context and pass the --disable-extensions-except and --load-extension flags pointing at your build folder.

import { chromium } from '@playwright/test';
import path from 'node:path';

const extensionPath = path.resolve('dist');
const context = await chromium.launchPersistentContext('', {
  channel: 'chromium',
  args: [
    `--disable-extensions-except=${extensionPath}`,
    `--load-extension=${extensionPath}`,
  ],
});
const page = await context.newPage();
await page.goto('https://example.com');
// assert on what your content script changed

Recent branded Chrome builds stopped honouring the --load-extension flag, so run automated tests against Chromium or Chrome for Testing, not your everyday Chrome. If a flag change breaks your tests after an update, check the Playwright and Chrome extension documentation.

How do you run tests and builds in CI?

Run the same commands you run locally: install, type-check, unit tests, build, then end-to-end tests against the build output. GitHub Actions or any CI runner with Node can do it.

1. Install dependencies with a locked install command such as npm ci so builds are reproducible.
2. Run the type check and linter as separate steps, so failures are easy to read.
3. Run unit tests with your test runner.
4. Build the extension and keep the output folder as an artifact.
5. Install the browser your end-to-end tests use, then run them against the built folder.
6. Zip the build output and upload it as the release artifact.

Extension tests need a real browser window on some setups. On Linux runners, wrap the test command in a virtual display such as xvfb-run if your browser mode requires one, or use a headless mode that supports extensions.

Publishing can be automated through the Chrome Web Store API with a service credential stored as a CI secret. Tools such as WXT include submit helpers, and community CLIs wrap the same API. Automate upload first and keep the final publish click manual until you trust the pipeline.

What should you check before publishing to the Chrome Web Store?

Check the manifest, permissions, privacy disclosures and store listing, then upload a clean production build. Review time can vary, so leave slack before any launch date.

• Permissions: remove every permission and host pattern you do not use. Broad access invites slower review and fewer installs.
• Version: raise version in manifest.json for every upload, because the store rejects a repeat.
• Privacy: be ready to explain what data the extension handles and why, and keep your listing consistent with what the code does.
• Remote code: Manifest V3 does not allow loading and running remotely hosted code, so bundle every script.
• Assets: prepare icons, screenshots and a clear description before you submit.
• Production build: test the zip you upload, not the dev build, on a clean profile.

Extension developers often scrape or read pages too. If that is part of your project, our web scraper use-case page covers the tools users already rely on, and the AI tools for developers roundup covers coding helpers. Official documentation on developer.chrome.com stays the source of truth for policy details.