Dev command for watch mode and live reload

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

Capability	What it gives you
Watch mode iteration	Tight edit → rebuild → validate loop while coding
Browser-target control	Explicit cross-browser validation per command
Profile-aware runs	Reliable fresh or persisted profiles by workflow need

Usage

extension dev [path-or-url] [options]

extension dev [path-or-url] [options]

extension dev [path-or-url] [options]

extension dev [path-or-url] [options]

extension dev [path-or-url] [options]

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.

Flag	What it does	Default
`--browser <target>`	Target Chrome, Edge, Firefox, or comma-separated list.	`chromium`
`--polyfill`	Bridge `browser.*` API to Chromium targets for Firefox-flavored sources.	`true`
`--port <port>`	Dev server port. Use `0` for OS-assigned.	`8080`
`--starting-url <url>`	Open this URL when the browser launches.	unset
`--no-reload`	Skip auto-reload. Use when you want a clean dev bundle.	reload on

Arguments and flags

Flag	Alias	What it does	Default
`[path or url]`	-	Extension path or remote URL.	`process.cwd()`
`--browser <browser>`	`-b`	Browser/engine target (`chromium`, `chrome`, `edge`, `firefox`, named forks like `brave`/`waterfox`, engine aliases, or comma-separated values).	`chromium`
`--profile <path\|boolean>`	-	Browser profile path or boolean profile mode.	fresh profile
`--chromium-binary <path>`	-	Custom Chromium-family binary path.	system default
`--gecko-binary <path>`	`--firefox-binary`	Custom Gecko-family binary path.	system default
`--polyfill [boolean]`	-	Enable `browser.*` API compatibility polyfill for Chromium targets.	`true`
`--no-polyfill`	-	Disable the cross-browser polyfill.	polyfill enabled
`--starting-url <url>`	-	Starting URL in launched browser.	unset
`--port <port>`	-	Requested dev server port. Use `0` for an OS-assigned port. See how the port resolves.	`8080`
`--host <host>`	-	Host to bind the dev server to. Use `0.0.0.0` for Docker/dev containers.	`127.0.0.1`
`--public-host <host>`	-	Connectable host the browser dials for HMR and the reload bridge, when it differs from the bind `--host` (remote/dev container).	bind host (`127.0.0.1` when bound to `0.0.0.0`)
`--no-open`	-	Do not automatically launch browser.	browser launches by default
`--no-browser`	-	Do not launch browser.	browser launch enabled
`--no-reload`	-	Skip the content-script reload runtime and on-rebuild reload dispatch. Reload tabs manually to see changes.	reload runtime enabled
`--wait [boolean]`	-	Wait for `dist/extension-js/<browser>/ready.json` and exit. Requires a local project path.	disabled
`--wait-timeout <ms>`	-	Timeout for `--wait` mode.	`60000`
`--output <pretty\|json>`	-	Result format. `json` prints a schema-1 envelope on stdout.	`pretty`
`--extensions <list>`	-	Comma-separated companion extensions or store URLs.	unset
`--install [boolean]`	-	Internal flag. Install project dependencies when missing. Lifecycle scripts stay disabled unless `EXTENSION_ALLOW_INSTALL_SCRIPTS=true`.	command behavior default
`--allow-control`	-	Enable the agent-bridge control channel for the bounded act verbs (`reload`, `storage`, `open`).	disabled
`--allow-eval`	-	Also enable `extension eval`. Implies `--allow-control` and writes a `0600` session token.	disabled
`--parent-pid <pid>`	-	Exit the dev server as soon as the given process ID dies. See parent watchdog.	unset
`--debug`	-	Enable maintainer diagnostics.	disabled

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.

Flag	What it does	Default
`--safari-binary <path>`	Safari binary to open after packaging.	system Safari
`--app-name <name>`	Override the Safari app name.	the manifest `name`
`--bundle-id <id>`	User-owned bundle identifier in reverse-DNS form. A malformed value fails before any build.	a generated `dev.extensionjs.*` id
`--macos-only [boolean]`	Generate a macOS-only Xcode project. Pass `false` for a universal macOS + iOS project.	`true`
`--force-regenerate`	Regenerate the Safari Xcode project even when up to date.	disabled

For Safari targets, dev also runs a toolchain preflight before the first bundle. A missing Xcode fails fast with E_SAFARI_TOOLCHAIN.

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.

Automation metadata (recommended for scripts/agents)

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
status: "error" for startup/compile failures
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
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
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.

`--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:

Run extension dev --no-browser as 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. If you pass both --wait and --no-browser in the same command invocation, --wait takes precedence. The command runs in wait-only mode.

Machine output with `--output json`

--output json prints schema-1 envelopes on stdout, one JSON object per line:

A plain dev run prints one status: "started" frame at startup. 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. Read ready.json for the live state.
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.

`--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.

Logging flags

These flags are experimental and may change between minor releases.

Flag	What it does	Default
`--logs <off\|error\|warn\|info\|debug\|trace\|all>`	Minimum log level.	`off`
`--log-context <list\|all>`	Context filter (`background`, `content`, `page`, `sidebar`, `popup`, `options`, `devtools`).	`all`
`--log-format <pretty\|json\|ndjson>`	Logger output format.	`pretty`
`--no-log-timestamps`	Disable timestamps in pretty mode.	timestamps enabled
`--no-log-color`	Disable color in pretty mode.	color enabled
`--log-url <pattern>`	Filter log events by URL substring/regex.	unset
`--log-tab <id>`	Filter log events by tab ID.	unset

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:

extension dev .            # run from the monorepo root

When exactly one extension package is found, Extension.js resolves it and prints:

Workspace root detected — resolved extension package: packages/my-extension

When several candidates exist, it lists them so you can point at the one you mean:

extension dev packages/my-extension

Examples

Running a local extension

extension dev ./my-extension

extension dev ./my-extension

extension dev ./my-extension

extension dev ./my-extension

extension dev ./my-extension

Running a remote extension from GitHub

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

extension dev https://github.com/nicedoc/browserless/tree/main/packages/screencast

extension dev https://github.com/nicedoc/browserless/tree/main/packages/screencast

extension dev https://github.com/nicedoc/browserless/tree/main/packages/screencast

extension dev https://github.com/nicedoc/browserless/tree/main/packages/screencast

extension dev https://github.com/nicedoc/browserless/tree/main/packages/screencast

Running in Firefox

extension dev ./my-extension --browser firefox

extension dev ./my-extension --browser firefox

extension dev ./my-extension --browser firefox

extension dev ./my-extension --browser firefox

extension dev ./my-extension --browser firefox

Running in multiple browsers in sequence

extension dev ./my-extension --browser=chrome,firefox

extension dev ./my-extension --browser=chrome,firefox

extension dev ./my-extension --browser=chrome,firefox

extension dev ./my-extension --browser=chrome,firefox

extension dev ./my-extension --browser=chrome,firefox

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:

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0

Combine with --port 0 to let the OS choose an available port automatically:

extension dev ./my-extension --host 0.0.0.0 --port 0

extension dev ./my-extension --host 0.0.0.0 --port 0

extension dev ./my-extension --host 0.0.0.0 --port 0

extension dev ./my-extension --host 0.0.0.0 --port 0

extension dev ./my-extension --host 0.0.0.0 --port 0

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.

# Browser on another machine reaches the dev server at devbox.local
extension dev ./my-extension --host 0.0.0.0 --public-host devbox.local

extension dev ./my-extension --host 0.0.0.0 --public-host devbox.local

extension dev ./my-extension --host 0.0.0.0 --public-host devbox.local

extension dev ./my-extension --host 0.0.0.0 --public-host devbox.local

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.

Running in Brave as a custom binary

extension dev ./my-extension --chromium-binary /path/to/brave

extension dev ./my-extension --chromium-binary /path/to/brave

extension dev ./my-extension --chromium-binary /path/to/brave

extension dev ./my-extension --chromium-binary /path/to/brave

extension dev ./my-extension --chromium-binary /path/to/brave

Best practices

Browser compatibility: Test your extension in different browsers to verify it works on every target.
Polyfilling: The polyfill is on by default in dev, so browser.* calls work in Chromium-based browsers. Pass --no-polyfill when you want the raw bundle.
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

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.

Introduction

Browser extension fundamentals

Getting started

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Dev command for watch mode and live reload

When to use `dev`

Dev command capabilities

Usage

Most-used flags

Arguments and flags

Safari flags

Parent watchdog

How the port resolves

Automation metadata (recommended for scripts/agents)

`--no-browser` and readiness synchronization

Machine output with `--output json`

`--no-reload` for a clean dev bundle

Logging flags

Shared global options

Monorepo and workspace roots

Examples

Running a local extension

Running a remote extension from GitHub

Running in Firefox

Running in multiple browsers in sequence

Running inside Docker or a dev container

Bind host vs. connectable host

Running in Brave as a custom binary

Best practices

Next steps

​When to use dev

​Dev command capabilities

​Usage

​Most-used flags

​Arguments and flags

​Safari flags

​Parent watchdog

​How the port resolves

​Automation metadata (recommended for scripts/agents)

​--no-browser and readiness synchronization

​Machine output with --output json

​--no-reload for a clean dev bundle

​Logging flags

​Shared global options

​Monorepo and workspace roots

​Examples

​Running a local extension

​Running a remote extension from GitHub

​Running in Firefox

​Running in multiple browsers in sequence

​Running inside Docker or a dev container

​Bind host vs. connectable host

​Running in Brave as a custom binary

​Best practices

​Next steps

When to use `dev`

Dev command capabilities

Usage

Most-used flags

Arguments and flags

Safari flags

Parent watchdog

How the port resolves

Automation metadata (recommended for scripts/agents)

`--no-browser` and readiness synchronization

Machine output with `--output json`

`--no-reload` for a clean dev bundle

Logging flags

Shared global options

Monorepo and workspace roots

Examples

Running a local extension

Running a remote extension from GitHub

Running in Firefox

Running in multiple browsers in sequence

Running inside Docker or a dev container

Bind host vs. connectable host

Running in Brave as a custom binary

Best practices

Next steps