Skip to main content
Use dev for day-to-day browser extension development with watch mode, browser launch, and context-aware update behavior. dev runs the development pipeline and watches your project files. It applies update strategies based on what changed: hot module replacement (HMR), hard reload, or a full restart when the change requires it.

When to use dev

  • Building features and validating changes in real time.
  • Debugging extension behavior in one or more browser targets.
Use build for production artifacts, start for production build + launch, and preview to run existing build output only. If your extension lives inside a monorepo/submodule, review how extension.config.* loads env files (including workspace-root fallback): Environment variables.

Dev command capabilities

What triggers a rebuild

The watcher follows the build graph: the manifest and everything it names, each entry and its imports, the pages/, scripts/ and public/ folders, _locales/, and the project config and env files. A write anywhere else in the project, such as a screenshot under store/, a demo page, a README or a test fixture, never rebuilds or reloads the extension. A special folder created while dev runs is picked up on the next compile. From the release after 4.1.39, a project under a symlinked folder is watched by one path. On macOS, the first build waits a bounded time for the watcher’s first scan before it reports ready. An early save is then not missed. From the release after 4.1.41, a save rebuilds a page while the build has an error. That covers the page and every file that it names. The save that fixes the error updates the page. dev also rebuilds for a new locale folder, a new file beside messages.json, and a new _locales folder. From the release after 4.1.41, a CSS url() or a require() that names a missing file is watched, so creating that file rebuilds the session. On macOS, a file added to public/ ships for the whole session. Earlier releases could stop shipping new public/ files after a rescan landed while a scan ran. From the release after 4.1.41, a restart of the compiler also cleans the output:
  • When a manifest edit removes an entry, the restart removes that entry’s files from dist/<browser>.
  • Deleting or renaming a file under pages/ or scripts/ restarts the compiler by itself, as adding one already does. The restart removes the outputs of files that are gone. You do not restart the command.

Usage

The CLI is not installed globally. npx extension@latest dev downloads the current release and runs it, so extension alone is not a command in your shell. Inside a project that create made, npm run dev runs the same command through the dev script in package.json.
If you omit the path, Extension.js uses the current working folder. You can also pass a GitHub tree URL (for example, https://github.com/user/repo/tree/main/path). Extension.js downloads the repository and runs development mode on the local copy.

Most-used flags

These cover the 80% case. Skip to the full reference for the rest.

Arguments and flags

On Firefox, --starting-url opens after the add-on installs, so your document_start content scripts run on that page. From the release after 4.1.39, it no longer replaces a tab that your extension opened. Two deprecated aliases are hidden from --help but still work:
  • --wait-format <pretty|json> maps onto --output and warns once on stderr. Migrate scripts to --output.
  • --author and --author-mode map onto --debug.

Safari flags

These flags apply to safari and webkit-based targets only. Passing any of them with another target exits with E_INVALID_OPTION, so a typo never no-ops silently. For Safari targets, dev also runs a toolchain preflight before the first bundle. A missing Xcode fails fast with E_SAFARI_TOOLCHAIN. From 4.1.20, a Safari session is a full dev session. Once you enable the extension in Safari Settings, extension logs reads it, the control bridge attaches, and every save reloads the extension in Safari. See Building Safari extensions.

Emulated Chromium

From 4.1.38, --browser=chromium-emulator runs your extension in an emulated Chromium inside a web page, with no flag or environment variable to set. dev prints the page address and opens it in your default browser. The page reads your build from the dev server on your machine, so only dev opens this target. start and preview refuse it. Before it opens the page, dev checks that the engine origin answers. When the origin does not answer, dev prints one warning and opens nothing:
The dev server keeps running. --logs has no effect on this target: the extension runs in a web page, so read its console in your browser’s devtools on that page.

Parent watchdog

--parent-pid is for harnesses and agents that spawn dev, so a crashed owner cannot leak a server. The value must be a positive integer, anything else exits with E_INVALID_OPTION. The watchdog polls the parent process every 2 seconds. When the parent is gone, the dev server shuts down via SIGTERM, with a 5 second hard-exit backstop if cleanup wedges.

How the port resolves

--port is a request, not a guarantee. When the requested port is busy, the dev server walks upward to the nearest free port. --port 0 asks the OS for any free port. Read the bound port from ready.json, not from the flag you passed. --port sets the dev server port only. The control bridge listens on its own port, and no flag sets it. On the first run, the session asks the OS for a free port and stores it in .extension-js/control-port-<browser>. The next run asks for the same port, so a browser profile that still holds the old one can reconnect. When that port is busy, the OS assigns another. Read it from controlPort in ready.json.

What dev adds to your extension

A dev session grants itself what the reload needs, and the production build of the same source has none of it. From the release after 4.1.39, the session names each addition under the identity card:
  • A Dev only line lists the permissions, host access, or web accessible resources that only the dev manifest has.
  • From the release after 4.2.0, a Dev only line that starts with manifest names the other manifest fields that the dev build changed and the production build does not have, such as content_security_policy 'unsafe-eval', externally_connectable.ids *, or background.persistent true.
  • A Dev flag line names a launch flag that changes what you see, and the config key that flips it.
  • A Dev pref line names a browser preference that the session wrote to a profile that outlives it. See Browser preferences.
ready.json lists every entry with its reason under devAdditions. Nothing on these lines ships. Run extension build and read dist/<browser>/manifest.json to see what a store receives.

The first page waits for boot registrations

A background script can register content scripts as it starts, with scripting.registerContentScripts. A page that loads before that call answers never runs the registered script. From the release after 4.1.39, dev holds the first page until the background finishes its startup work. That covers a registration made after awaited calls, such as a fetch or a storage read. The wait is bounded at about five seconds, so the page always opens. A registration behind a timer is not waited for. dev cannot tell when a setTimeout callback or an alarm will fire. The CLI can print two lines. The first one prints when the wait runs out:
The second one prints when a registration arrives after the page opened:
In both cases, reload the page if the script did not run on it. A registered script runs only on pages that load after the registration. Firefox can still run the script on a page it was already opening, so check before you reload. start and preview hold the first page the same way, for a registration made as the background starts or after a storage read. They do not wait for a registration behind an awaited fetch or a timer. For those, they print the second line when the registration arrives in the first 15 seconds. When dev runs, Extension.js emits machine-readable metadata under:
  • dist/extension-js/<browser>/ready.json
  • dist/extension-js/<browser>/events.ndjson (newline-delimited JSON)
For automation (Playwright, continuous integration (CI), AI agents), prefer these files over terminal log parsing. Treat ready.json as the readiness contract:
  • status: "starting" while booting
  • status: "ready" when the build compiled. From the release after 4.1.39, with --allow-control or --allow-eval and a launched browser, ready also waits up to 10 seconds for the background to connect. From the release after 4.1.41, with a browser to launch, status stays starting after the compile and turns ready once the launcher has stamped browserPid, binary, profilePath and the debugger port (cdpPort on Chromium, rdpPort on Firefox). executorAttachedAt can follow ready unless the session was started with --allow-control or --allow-eval, where ready waits for it up to 10 seconds
  • status: "error" for startup/compile failures, and for a browser that never started (code: "browser_launch_failed") or exited before the extension loaded (code: "browser_exited")
  • status: "stopped" after the session shut down, so a dead session never advertises ready
  • runtime: "attached" (with executorAttachedAt) once the service worker connected. Act verbs should wait for this, not for ready
  • runtime: "detached" (with executorDetachedAt) from 4.1.20, once the last connected extension context disconnects. executorAttachedAt stays as provenance, and the value goes back to "attached" on reconnect
  • runId uniquely identifies a runtime session
  • startedAt marks the runtime session start timestamp
  • command names the producing command (dev, start, preview, or build)
  • toolchainVersion, extensionName, and extensionVersion record which Extension.js version produced the tree, for which extension. The file doubles as a build receipt after the terminal scrollback is gone
  • port is the bound dev server port, and host is the connectable host clients dial (see bind host vs. connectable host)
  • controlPort / instanceId locate the control bridge used by extension logs and the act verbs
  • cdpPort (Chromium) and rdpPort (Gecko) expose the browser debugging ports. From the release after 4.1.41, sessions started at the same time each get their own debugging port, so read these fields instead of assuming 9222
  • profilePath, browserPid, and extensionId are stamped by the browser launcher after launch
The full schema, error states, and two-phase readiness rules live in the ready.json contract. events.ndjson is scoped to the current run: starting a new run resets the file, and every entry is stamped with the run’s runId (matching ready.json), so consumers never see events from a previous session interleaved with the live one. When a session misbehaves, run extension doctor: it walks the contract, control channel, token, executor, and browser in order and names the first failing leg with a fix.

Stop the browser from launching

Two flags sound alike and do different things:
--no-browser is the run mode for headless, CI, and remote work, and it is the flag the Playwright end-to-end workflow is built on. It also has a config form, commands.dev.noBrowser: true, and an environment form, EXTENSION_CLI_NO_BROWSER=1. --no-open is a launch detail. Reach for it when you want the browser open on whatever it already shows, without Extension.js opening a tab for your extension over it. dev, start, and preview all accept both flags.

--no-browser and readiness synchronization

--no-browser disables browser launch but keeps the full dev loop. The dev server still watches your files, and on each rebuild it broadcasts a reload over the control bridge to the extension’s service worker so your changes apply without a launched browser driving them:
  • A content-script change is re-injected into the already-open matching tabs in place (the service worker runs chrome.scripting.executeScript with the fresh build), so the page updates on save without a manual refresh. Tabs opened afterward get the new build too, because the service worker re-registers the content scripts dynamically (chrome.scripting.registerContentScripts).
  • A service-worker / manifest change restarts the extension.
So --no-browser behaves like a normal dev session for headless, continuous integration (CI), and remote/dev-container workflows: load the built dist/<browser> into any browser you control and it keeps updating on save. (Use --no-reload for a static dev bundle that never reloads. See below.) --no-browser does not block external runners until the compile finishes. For Playwright/CI/AI workflows:
  1. Run extension dev --no-browser as a long-lived process.
  2. Run extension dev --wait --browser=<browser> as the readiness gate.
  3. Launch external browser automation only after status: "ready".
--wait targets a second process (or CI step) and exits non-zero on error/timeout. When --wait sees a stale ready.json from a dead process (pid no longer alive), it keeps waiting for a live producer. --wait requires a local project path. Passing a remote URL exits with E_ARGS. Passing both --wait and --no-browser in the same command invocation exits with E_INVALID_OPTION, because --wait only reads a contract that another process writes. Run them as two processes, as in the steps above. From 4.1.21, a --wait that reads ready.json while the producer is still writing it treats the half-written file as one more transient state and keeps polling. Up to 4.1.20, one torn read failed the wait with a JSON parse error. A file that never parses still ends in E_READY_TIMEOUT, and the timeout message names the cause: The last read of the file failed to parse as JSON, followed by the parser’s own error.

Machine output with --output json

--output json prints a schema-1 envelope on stdout:
  • A plain dev run prints one status: "started" frame as the first stdout line, once the session exists and right before the starting frame. It carries the project path, browser list, requested port, and the dev server pid. dev never terminates on its own, so no result frame follows. The lifecycle frames (starting, compiled, ready, and the ones after) follow on stdout, and human progress lines go to stderr, so every stdout line parses as JSON. Read ready.json for the live state.
  • A run refused before the session exists prints one ok: false frame and nothing else, with no started frame before it. That covers a missing manifest (E_MANIFEST_NOT_FOUND), a manifest that does not parse (E_MANIFEST_INVALID), a config file that fails to load (E_CONFIG_LOAD), and a remote URL that gives no usable archive (E_REMOTE_ZIP_INVALID, E_REMOTE_FETCH_TIMEOUT, E_REMOTE_ACCESS_DENIED, or E_REMOTE_DOWNLOAD).
  • A bad --chromium-binary or --gecko-binary pin does not stop the server. That covers a path that does not exist, a file that is not executable, and a binary that does not answer its version probe within 10 seconds. The contract goes to error with code browser_launch_failed and browserLaunchFailedCode: "E_BROWSER_BINARY_INVALID". The failure frame carries that readyCode with status: "usage" and error.code: "E_BROWSER_BINARY_INVALID", and a dev --wait against the session answers with the same status and code.
  • A pinned binary that is executable but that the system cannot start also keeps the server up. Its failure frame has status: "failed", error.code: "E_READY_ERROR_STATUS", and the browser_launch_failed readyCode.
  • A dev --wait run prints one status: "ready" frame on success. Its value.results array carries the full ready contract per browser.
  • Failures print one ok: false frame with an error.code (for example E_READY_TIMEOUT) before the process exits 1. A contract in error status names its cause: E_BROWSER_BINARY_INVALID with status: "usage" when the pinned binary was refused, E_BROWSER_LAUNCH when the browser never started, E_BROWSER_EXITED when it exited before the extension loaded, and E_COMPILE for a compile error. See the ready.json contract for the full list.
  • From the release after 4.1.41, a browser that refuses to load the extension does not stop the session. The stream carries one ok: false frame with status: "load-refused" and error.code: "E_EXTENSION_LOAD_REFUSED". A dev --wait against the session answers the same status and code and exits 1. The session tries the load again on the next save. See Manifest refusals.
  • From the release after 4.1.41, a refusal while dev is still finding the project prints nothing on stderr.
  • A later failure, such as a config file that throws, also prints its human lines on stderr.
  • From the release after 4.1.41, a restart that cannot build sends a restart-failed frame.
  • The previous build keeps serving. See Restarts and shutdown.
  • The last frame of every session is stopped or failed.

--no-reload for a clean dev bundle

--no-reload skips the content-script reinjection wrapper and the on-rebuild reload dispatch. The dev dist stays close to a production bundle and an open tab is not disturbed when files change. Reload the extension or page yourself to pick up changes. --no-reload is only supported on extension dev. Passing it to start, preview, or build exits with an error. Internally it sets EXTENSION_NO_RELOAD=true so the develop process can read it from outside the CLI argv. Dev builds emit cheap-module-source-map files that describe your source: the original TypeScript and the exact lines, for content scripts, classic multi-file groups, the background, and pages on both manifest versions. No eval variant is used, so the bundle runs under your own CSP.

Logging flags

These flags are experimental and may change between minor releases.

Shared global options

Also supports Global flags.

Monorepo and workspace roots

You can point dev (and build) at the root of a monorepo instead of the extension package itself. Extension.js detects the workspace root and auto-resolves the extension package inside it:
When exactly one extension package is found, Extension.js resolves it and prints:
When several candidates exist, it lists them so you can point at the one you mean:

pnpm workspace members install from the root

From 4.1.18, when the project is a member of a pnpm workspace and its dependencies are missing, the automatic install runs from the workspace root instead of the package folder. The install is filtered to the member and its workspace dependencies:
The lockfile and the linker layout stay the workspace’s, so the result matches a pnpm install at the root. The session prints one info line before the install runs:

Automatic dependency install

When dev or build finds the project dependencies missing, it installs them before it compiles. From the release after 4.1.41, only the project’s own package manager runs that install. Extension.js chooses it in this order:
  1. A lockfile at the project root: pnpm-lock.yaml, yarn.lock, bun.lockb, bun.lock, then package-lock.json.
  2. The packageManager field in package.json.
  3. EXTENSION_JS_PACKAGE_MANAGER, or a manager path in EXTENSION_JS_PM_EXEC_PATH or npm_execpath.
  4. A Deno project: a deno.lock, or a deno.json or deno.jsonc with no package.json beside it.
  5. The manager that ran the command, read from the first word of npm_config_user_agent.
  6. npm.
Extension.js never checks which managers are on your PATH to make this choice, so every machine chooses the same manager for the same project. When the chosen manager fails, the command stops with E_DEPENDENCY_INSTALL. No other manager tries in its place, because it would build a tree that the lockfile does not describe. When the chosen manager is not installed, the message says so and tells you how to install it.

Retries while a new release reaches the registry

A new release takes a minute or two to reach the whole npm registry. From the release after 4.1.41, the install runs again when the registry caused the failure:
  • The registry lists a version but does not serve its tarball yet.
  • A dependency of a dependency asks for a version that the registry does not list yet.
  • The registry answers with a 5xx or 429 status, resets the connection, times out, or fails a DNS lookup.
A version range that your own project declares is not retried, because only you can fix it. Authentication errors (401 and 403), disk and permission errors, and peer dependency conflicts are not retried either. The install runs up to 4 times. It waits 5, 10, and then 20 seconds between attempts, 35 seconds in all. Each wait prints a warning that names the cause and the next attempt:
When the last attempt fails too, the command stops with E_DEPENDENCY_INSTALL:
When the registry itself did not answer, the third line starts with “The registry is having trouble answering right now.” instead.

Refusals that are never retried

Two failures stop the install at once with E_DEPENDENCY_INSTALL. Extension.js never retries them and never works around them. A release that is too new. pnpm minimumReleaseAge and the Deno minimum dependency age refuse a release younger than the limit. The message names the rule and, when the manager printed it, the release. To continue, wait until the release is old enough, or pin the previous version. You can also lift the rule for that package: add it to minimumReleaseAgeExclude for pnpm, or set minimumDependencyAge in deno.json for Deno. A manager that Corepack cannot download. The manager never starts. The message names the registry that Corepack asked, and the HTTP status when there is one. It also says when Extension.js chose that registry because npm_config_registry or the project’s .npmrc names it. Check that the registry serves the manager and that you can reach it, or set COREPACK_NPM_REGISTRY to a registry that does.

Examples

Running a local extension

Running a remote extension from GitHub

Pass a GitHub tree URL as the argument to develop a remote extension locally:

Running in Firefox

Running in multiple browsers in sequence

Running inside Docker or a dev container

When you run inside Docker, dev containers, or GitHub Codespaces, bind the dev server to 0.0.0.0 so the host machine can reach it:
Combine with --port 0 to let the OS choose an available port automatically:

Bind host vs. connectable host

--host is the address the dev server binds to. The browser (the HMR client and the reload bridge) needs an address it can actually connect to, which is not always the same value:
  • --host 0.0.0.0 binds every interface, but 0.0.0.0 is not a connectable address. Extension.js automatically advertises 127.0.0.1 to the browser instead, the right target for the common port-forwarded Docker/dev-container/Codespaces setup, where the browser runs on the host and the port is forwarded to the container.
  • For a true remote setup (the browser runs on a different machine than the dev server), pass --public-host with the address the browser can reach (an LAN IP or hostname). It is propagated to the HMR client URL, ready.json, and the reload bridge baked into the extension.
When --host is a concrete address already (for example --host 192.168.1.50), that value is connectable as-is and is used directly. --public-host is only needed when the bind host and the browser-facing host differ. The dev server checks the Host header of every request, as a defense against DNS rebinding. It answers localhost, IP addresses, the bind host and --public-host. A request under any other name gets 403 with a plain-text body that names the refused host and the fix, and the terminal prints one line per refused host. Allow extra names with --allowed-hosts, a comma-separated list where a leading dot allows every subdomain, or with commands.dev.allowedHosts in extension.config.js (an array or a comma string). Use it when the dev server is reached under a docker service name, a tunnel hostname or an mDNS name, without changing what the browser dials.
--host 0.0.0.0 alone does not allow every name. The bind address and the allowed names are separate settings.

Running in Brave as a custom binary

Best practices

  • Browser compatibility: Test your extension in different browsers to verify it works on every target.
  • Polyfilling: The polyfill is off by default in dev. Chromium 148 and later expose browser natively, so pass --polyfill only for older versions. An extension that declares a devtools_page has no browser object in any script on Chromium below 152. See Cross-browser compatibility.
  • Automation reliability: Treat dev as the watch-mode companion (--no-browser + dev --wait). Treat start as the production companion (--no-browser + start --wait). Use --output=json for scripts and CI automation.

Next steps