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

CapabilityWhat it gives you
Build-output validationTest real production artifacts without rebuilding
Browser-target checksRun compiled output against selected browser targets
Runner controlLaunch or skip browser runner based on workflow needs
Fast manual QAVerify packaging-ready behavior quickly before release
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

extension preview [project-path] [options]
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 just 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

FlagAliasWhat it doesDefault
[path]-Preview built extension from a project path.process.cwd()
--browser <browser>-Browser/engine target (chromium, chrome, edge, firefox, etc.).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
--starting-url <url>-Starting URL in launched browser.unset
--no-browser-Skip browser launch.browser launch enabled
--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/dev containers.127.0.0.1
--extensions <list>-Comma-separated companion extensions or store URLs.unset
--author--author-modeEnable maintainer diagnostics.disabled

​
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

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 preview)

The CLI detects these flags and exits with an error before parsing. Use dev --source ... instead.
FlagSupport in preview
--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

​
Previewing a local extension

extension preview ./my-extension

​
Previewing in Edge and Chrome

extension preview ./my-extension --browser=edge,chrome

​
Preview without launching the browser

extension preview ./my-extension --no-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).
  • preview does not support source inspection flags; use dev for that workflow.
  • 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