Skip to main content
Launch an already-built extension output for production-like manual testing. preview does not compile your project. It loads an existing unpacked extension root and runs the browser launcher flow.

​
When to use preview

  • Running existing build output without rebuilding.
  • Comparing packaged behavior across browser targets quickly.
  • Debugging runtime issues tied to production artifacts rather than dev/watch mode.

​
Preview command capabilities

preview is run-only. It prefers dist/<browser> when that output exists. You can also point it at another unpacked extension folder that already contains a manifest.json.

​
Usage

If you omit the path, Extension.js uses the current working folder.

​
How preview chooses what to run

preview checks these locations in order:
  1. dist/<browser> for the selected browser target.
  2. The provided project path or current working folder.
The folder needs to contain an unpacked extension with a manifest.json. It does not matter whether a build ran in the same command.

​
Arguments and flags

​
Automation metadata

preview writes readiness metadata to:
  • dist/extension-js/<browser>/ready.json
For --no-browser flows, this provides deterministic command state:
  • starting while command initializes
  • ready when run-only validation is complete
  • error when required output is missing or startup fails
  • runId and startedAt for session correlation in scripts/agents
preview does not provide a --wait gate flag. For preview automation, consume ready.json directly.

​
Logging flags

​
Shared global options

Also supports Global flags.

​
Examples

​
Previewing a local extension

​
Previewing in Edge and Chrome

​
Preview without launching the browser

​
Behavior notes

  • preview is run-only and never compiles the project.
  • preview prefers existing build output (dist/<browser>) but can fall back to another unpacked extension root.
  • preview does not run watch mode or hot module replacement (HMR).
  • For scripts/agents, rely on ready.json and avoid parsing terminal output.

​
Best practices

  • Run build before preview when testing a fresh production artifact.
  • Pass the project path argument when your unpacked extension lives outside the default project output.
  • Use --browser to verify behavior across targets before packaging.

​
Next steps