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

​
--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. If you pass both --wait and --no-browser in the same 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 start run prints one status: "started" frame before the build. It carries the project path, browser list, requested port, and pid.
  • A start --wait run prints one status: "ready" frame on success. Its value.results array carries the full ready contract per browser.
  • A failed build prints one ok: false frame with status: "build-failed" and error.code: "E_COMPILE" before the process exits 1.

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