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.
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, thepages/, 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/orscripts/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.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--outputand warns once on stderr. Migrate scripts to--output.--authorand--author-modemap onto--debug.
Safari flags
These flags apply tosafari 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:
--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 onlyline lists the permissions, host access, or web accessible resources that only the dev manifest has. - From the release after 4.2.0, a
Dev onlyline that starts withmanifestnames the other manifest fields that the dev build changed and the production build does not have, such ascontent_security_policy 'unsafe-eval',externally_connectable.ids *, orbackground.persistent true. - A
Dev flagline names a launch flag that changes what you see, and the config key that flips it. - A
Dev prefline 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, withscripting.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:
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.
Automation metadata (recommended for scripts/agents)
Whendev runs, Extension.js emits machine-readable metadata under:
dist/extension-js/<browser>/ready.jsondist/extension-js/<browser>/events.ndjson(newline-delimited JSON)
ready.json as the readiness contract:
status: "starting"while bootingstatus: "ready"when the build compiled. From the release after 4.1.39, with--allow-controlor--allow-evaland a launched browser,readyalso waits up to 10 seconds for the background to connect. From the release after 4.1.41, with a browser to launch,statusstaysstartingafter the compile and turnsreadyonce the launcher has stampedbrowserPid,binary,profilePathand the debugger port (cdpPorton Chromium,rdpPorton Firefox).executorAttachedAtcan followreadyunless the session was started with--allow-controlor--allow-eval, wherereadywaits for it up to 10 secondsstatus: "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 advertisesreadyruntime: "attached"(withexecutorAttachedAt) once the service worker connected. Act verbs should wait for this, not forreadyruntime: "detached"(withexecutorDetachedAt) from 4.1.20, once the last connected extension context disconnects.executorAttachedAtstays as provenance, and the value goes back to"attached"on reconnectrunIduniquely identifies a runtime sessionstartedAtmarks the runtime session start timestampcommandnames the producing command (dev,start,preview, orbuild)toolchainVersion,extensionName, andextensionVersionrecord which Extension.js version produced the tree, for which extension. The file doubles as a build receipt after the terminal scrollback is goneportis the bound dev server port, andhostis the connectable host clients dial (see bind host vs. connectable host)controlPort/instanceIdlocate the control bridge used byextension logsand the act verbscdpPort(Chromium) andrdpPort(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 9222profilePath,browserPid, andextensionIdare stamped by the browser launcher after launch
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.executeScriptwith 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.
--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:
- Run
extension dev --no-browseras a long-lived process. - Run
extension dev --wait --browser=<browser>as the readiness gate. - 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
devrun prints onestatus: "started"frame as the first stdout line, once the session exists and right before thestartingframe. It carries the project path, browser list, requested port, and the dev serverpid.devnever 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. Readready.jsonfor the live state. - A run refused before the session exists prints one
ok: falseframe and nothing else, with nostartedframe 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, orE_REMOTE_DOWNLOAD). - A bad
--chromium-binaryor--gecko-binarypin 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 toerrorwith codebrowser_launch_failedandbrowserLaunchFailedCode: "E_BROWSER_BINARY_INVALID". The failure frame carries thatreadyCodewithstatus: "usage"anderror.code: "E_BROWSER_BINARY_INVALID", and adev --waitagainst 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 thebrowser_launch_failedreadyCode. - A
dev --waitrun prints onestatus: "ready"frame on success. Itsvalue.resultsarray carries the full ready contract per browser. - Failures print one
ok: falseframe with anerror.code(for exampleE_READY_TIMEOUT) before the process exits1. A contract inerrorstatus names its cause:E_BROWSER_BINARY_INVALIDwithstatus: "usage"when the pinned binary was refused,E_BROWSER_LAUNCHwhen the browser never started,E_BROWSER_EXITEDwhen it exited before the extension loaded, andE_COMPILEfor 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: falseframe withstatus: "load-refused"anderror.code: "E_EXTENSION_LOAD_REFUSED". Adev --waitagainst the session answers the same status and code and exits1. The session tries the load again on the next save. See Manifest refusals. - From the release after 4.1.41, a refusal while
devis 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-failedframe. - The previous build keeps serving. See Restarts and shutdown.
- The last frame of every session is
stoppedorfailed.
--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 pointdev (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:
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:pnpm install at the root. The session prints one info line before the install runs:
Automatic dependency install
Whendev 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:
- A lockfile at the project root:
pnpm-lock.yaml,yarn.lock,bun.lockb,bun.lock, thenpackage-lock.json. - The
packageManagerfield inpackage.json. EXTENSION_JS_PACKAGE_MANAGER, or a manager path inEXTENSION_JS_PM_EXEC_PATHornpm_execpath.- A Deno project: a
deno.lock, or adeno.jsonordeno.jsoncwith nopackage.jsonbeside it. - The manager that ran the command, read from the first word of
npm_config_user_agent. - npm.
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.
E_DEPENDENCY_INSTALL:
Refusals that are never retried
Two failures stop the install at once withE_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 to0.0.0.0 so the host machine can reach it:
--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.0binds every interface, but0.0.0.0is not a connectable address. Extension.js automatically advertises127.0.0.1to 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-hostwith 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.
--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 exposebrowsernatively, so pass--polyfillonly for older versions. An extension that declares adevtools_pagehas nobrowserobject in any script on Chromium below 152. See Cross-browser compatibility. - Automation reliability: Treat
devas the watch-mode companion (--no-browser+dev --wait). Treatstartas the production companion (--no-browser+start --wait). Use--output=jsonfor scripts and CI automation.
Next steps
- Build production artifacts with
build. - Validate production launch flow with
start. - Review browser targeting with Browser-specific manifest fields.
- Configure shared defaults in
extension.config.js. - Review configuration env loading behavior in Environment variables.

