Skip to main content
Use start when you want a production build and immediate browser launch in one command. The start command runs a production build first, then launches the built extension using the same flow as the preview command.

​
When to use start

  • Manually validating production behavior right after compilation.
  • Reproducing runtime differences between watch mode and production output.
  • Running a production-like check locally without a separate build then preview step.

​
Start command capabilities

CapabilityWhat it gives you
Build + launch workflowRun production compile and browser launch in one step
Target selectionStart directly in selected browser or engine target
Runner controlSkip browser launch when you only need build verification
Production-like validationCheck real compiled output instead of watch-mode state

​
How it differs from other commands

  • dev: development server + hot module replacement (HMR)/watch loop
  • build: production build only
  • preview: launch an existing built extension without building
  • start: build + preview in sequence

​
Usage

extension start [path-or-url] [options]
If you omit the path, the command uses the current working folder.

​
Arguments and flags

FlagAliasWhat it doesDefault
[path or url]-Extension path or remote URL.process.cwd()
--browser <browser>-Browser/engine target.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-binaryCustom Gecko-family binary path.system default
--polyfill [boolean]-Enable browser.* API compatibility polyfill for Chromium targets.true
--starting-url <url>-Starting URL in launched browser.unset
--no-browser-Build but skip browser launch.browser launch enabled
--wait [boolean]-Wait for dist/extension-js/<browser>/ready.json and exit.disabled
--wait-timeout <ms>-Timeout for --wait mode.60000
--wait-format <pretty|json>-Output format for wait results (json is machine-readable).pretty
--port <port>-Runner/devtools port when runner is enabled. Use 0 for OS-assigned port.8080
--host <host>-Host to bind the dev server to. Use 0.0.0.0 for Docker/devcontainers.127.0.0.1
--extensions <list>-Comma-separated companion extensions or store URLs.unset
--install [boolean]-Install project dependencies when missing.command behavior default
--author--author-modeEnable maintainer diagnostics.disabled

​
Automation metadata

start writes readiness metadata to:
  • dist/extension-js/<browser>/ready.json
This is useful for automation when using --no-browser:
  • wait for status: "ready" before launching external runners
  • handle status: "error" as a deterministic failure signal
  • use runId and startedAt to correlate a specific runtime session

​
--no-browser and readiness synchronization

--no-browser only disables browser launch. It does not block external runners until the production build finishes. For production-oriented Playwright, continuous integration (CI), and AI workflows:
  1. run extension start --no-browser as the producer process
  2. run extension start --wait --browser=<browser> as the readiness gate
  3. launch external browser automation only after status: "ready"
--wait exits non-zero on error/timeout and ignores stale contracts from dead processes (pid no longer alive). If you pass both --wait and --no-browser in the same invocation, --wait takes precedence. The command runs in wait-only mode.

​
Logging flags

FlagWhat it doesDefault
--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-timestampsDisable timestamps in pretty mode.timestamps enabled
--no-log-colorDisable 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

​
Source inspection flags (not supported in start)

start accepts these flags in parsing, but exits with an error if you use them. Use dev --source ... instead.
FlagSupport in start
--source [url]not supported (command exits with guidance)
--watch-source [boolean]not supported (command exits with guidance)
--source-format <pretty|json|ndjson>not supported (command exits with guidance)
--source-summary [boolean]not supported (command exits with guidance)
--source-meta [boolean]not supported (command exits with guidance)
--source-probe <selectors>not supported (command exits with guidance)
--source-tree <off|root-only>not supported (command exits with guidance)
--source-console [boolean]not supported (command exits with guidance)
--source-dom [boolean]not supported (command exits with guidance)
--source-max-bytes <bytes>not supported (command exits with guidance)
--source-redact <off|safe|strict>not supported (command exits with guidance)
--source-include-shadow <off|open-only|all>not supported (command exits with guidance)
--source-diff [boolean]not supported (command exits with guidance)

​
Shared global options

Also supports global flags.

​
Examples

​
Start with default browser

extension start

​
Start in Firefox

extension start --browser firefox

​
Build and skip browser launch

extension start --no-browser

​
Behavior notes

  • start does not run a dev server and does not provide hot module replacement (HMR) or watch mode.
  • start is production-mode oriented; use dev for iterative local development.
  • start does not support source inspection options. Use dev --source ... for that workflow.
  • For machine consumers, parse dist/extension-js/<browser>/ready.json instead of terminal text.

​
Next steps

  • Iterate quickly with dev.
  • Launch existing build output with preview.