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

​
How it differs from other commands

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

​
Usage

If you omit the path, the command uses the current working folder.

​
Arguments and flags

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.

​
Browser support

start has no Safari path. Passing --browser safari (or webkit-based) exits with E_COMMAND_UNSUPPORTED_FOR_TARGET. The reason is measured. Safari’s WebDriver route does load an unpacked folder, and the background even runs, but Safari grants the extension zero host origins. Content scripts never inject, and no API call can grant the access afterwards. Use dev or build for Safari targets.

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

​
Stop the browser from launching

Two flags sound alike and do different things:
--no-browser also has a config form, commands.start.noBrowser: true, and an environment form, EXTENSION_CLI_NO_BROWSER=1. dev, start, and preview all accept both flags.

​
--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). Because start can finish quickly, a contract from a completed run still counts when its timestamp is within a 60 second window. --wait requires a local project path. Passing a remote URL exits with E_ARGS. Passing both --wait and --no-browser in the same 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.

​
Machine output with --output json

--output json prints schema-1 envelopes on stdout, one JSON object per line:
  • A plain start run prints one status: "started" frame once the build finished and the browser launched. It carries the project path, browser list, pid, and port: null, because a run-only session binds no port. A run that fails prints only its failure frame, never a started frame before it.
  • A start --wait run prints one status: "ready" frame on success. Its value.results array carries the full ready contract per browser.
  • A start --wait run that reads a contract in error status prints one ok: false frame that names the cause, for example E_BROWSER_LAUNCH when the browser never started or E_BROWSER_EXITED when it exited. See the ready.json contract for the full list.
  • A failed build prints one ok: false frame with status: "build-failed" before the process exits 1. A compile error carries error.code: "E_COMPILE". A missing project folder carries E_PROJECT_NOT_FOUND, a folder with no manifest carries E_MANIFEST_NOT_FOUND, and a manifest that does not parse carries E_MANIFEST_INVALID. A config file that fails to load carries E_CONFIG_LOAD, and a remote URL that gives no usable archive carries E_REMOTE_ZIP_INVALID, E_REMOTE_FETCH_TIMEOUT, or E_REMOTE_DOWNLOAD.
  • A bad --chromium-binary or --gecko-binary pin prints one ok: false frame with status: "usage" and error.code: "E_BROWSER_BINARY_INVALID". 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 command ends and leaves nothing running.
  • A browser that cannot start prints one ok: false frame with status: "failed". The code is E_BROWSER_LAUNCH when the binary is executable but the system cannot start it or Firefox exits before its debugger answers, and E_BROWSER_CONNECT when Firefox runs but its debugger never answers.

​
Logging flags

These flags are experimental and may change between minor releases.

​
Shared global options

Also supports Global flags.

​
Examples

​
Start with default browser

​
Start in Firefox

​
Build and skip browser launch

​
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.
  • 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.