Docs
Blog
Docs
Blog

Dev command

Use dev for day-to-day browser extension development with watch mode, browser launch, and context-aware update behavior.

dev runs the development pipeline, watches project files, and applies update strategies based on what changed (HMR, hard reload, or restart-required diagnostics).

When to use dev

  • Building features and validating changes in real time.
  • Debugging extension behavior in one or more browser targets.
  • Running source-inspection workflows with --source.

Use build for production artifacts, start for production build + launch, and preview to run existing build output only.

What dev gives you

Capability Outcome for developers
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
Source inspection mode Structured output and diagnostics with source flags

Usage

npm
pnpm
yarn
extension dev [path-or-url] [options]

If no path is provided, Extension.js uses process.cwd().

Core options

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, 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 compatibility polyfill behavior. false
--starting-url <url> - Starting URL in launched browser. unset
--port <port> - Dev server port. 8080
--no-open - Do not automatically open browser. browser opens by default
--no-runner - Do not launch browser runner. runner enabled
--extensions <list> - Comma-separated companion extensions or store URLs. unset
--install [boolean] - Install project dependencies when missing. command behavior default
--author --author-mode Enable maintainer diagnostics. disabled

Source inspection workflow

Use source options only with dev:

  • --source <url> to run from a remote extension source
  • --watch-source / --no-watch-source to control remote polling behavior

start and preview do not support source-inspection flags.

Source flags

Flag What it does Default behavior
--source [url] Enable source inspection flow. disabled
--watch-source [boolean] Re-print source output on watched updates. true when --source is enabled
--source-format <pretty|json|ndjson> Output format for source inspection. falls back to log format or json
--source-summary [boolean] Emit compact summary output. disabled
--source-meta [boolean] Include page metadata. enabled when source is on
--source-probe <selectors> Comma-separated CSS selectors to probe. unset
--source-tree <off|root-only> Include compact extension tree details. unset
--source-console [boolean] Include console summary. disabled
--source-dom [boolean] Include DOM snapshots/diffs. enabled when watch-source is on
--source-max-bytes <bytes> Cap output payload size. unset
--source-redact <off|safe|strict> Redaction strategy for source output. format-dependent
--source-include-shadow <off|open-only|all> Control Shadow DOM inclusion. open-only when source is on
--source-diff [boolean] Include diff metadata on watch updates. enabled when watch-source is on

Logging flags

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.

Examples

Running a local extension

Video demo soon: local dev workflow

npm
pnpm
yarn
extension dev ./my-extension

Running a remote extension

Video demo soon: remote source dev workflow

npm
pnpm
yarn
extension dev --source https://example.com/my-extension.zip

Running in Firefox

Video demo soon: firefox target dev workflow

npm
pnpm
yarn
extension dev ./my-extension --browser firefox

Running in multiple browsers in sequence

Video demo soon: multi-browser dev checks

npm
pnpm
yarn
extension dev ./my-extension --browser=chrome,firefox

Running in brave as a custom binary

Video demo soon: custom binary dev workflow

npm
pnpm
yarn
extension dev ./my-extension --chromium-binary /path/to/brave

Best practices

  • Browser compatibility: Test your extension in different browsers to ensure compatibility with the target audience.
  • Polyfilling: If Firefox or a Gecko-based browser is also a target, use the --polyfill flag to enable compatibility for the browser.* API in Chromium-based browsers.
  • Source inspection workflows: Use dev (not start/preview) when you need source inspection options.

Next steps

ON THIS PAGE