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

--author and --author-mode are hidden, deprecated aliases for --debug.

​
Browser support

preview has no Safari path. Passing --browser safari (or webkit-based) exits with E_COMMAND_UNSUPPORTED_FOR_TARGET. Safari is a supported browser, but this command cannot launch it. Use dev or build for Safari targets.

​
Remote URLs and light mode

When the path argument is a remote http(s) URL, preview sets EXTJS_LIGHT=1 automatically. This runs the launch in light mode for downloaded extensions. Set EXTJS_LIGHT yourself beforehand to override this behavior.

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

​
Machine output with --output json

--output json prints one schema-1 envelope on stdout:
  • A successful run prints a status: "ready" frame. Its value carries the project path and the list of previewed browsers.
  • When there is nothing to preview, the frame is ok: false with status: "not-found" and error.code: "E_PREVIEW_NO_DIST". Its hint says to run extension build first.
  • Other failures print ok: false with status: "failed" 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

​
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