Docs
Blog
Docs
Blog

Preview command

Launch an already-built extension output for production-like manual testing.

preview does not compile your project. It loads extension files from build output (typically dist/<browser>) 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

Capability What it gives you
Build-output validation Test real production artifacts without rebuilding
Browser-target checks Run compiled output against selected browser targets
Runner control Launch or skip browser runner based on workflow needs
Fast manual QA Verify packaging-ready behavior quickly before release

preview requires an existing built extension output. If dist/<browser> is missing, run build first.

Usage

npm
pnpm
yarn
extension preview [project-path] [options]

If no path is provided, process.cwd() is used.

Core options

Flag Alias What it does Default
[path] - Preview built extension from a project path. process.cwd()
--browser <browser> -b 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-binary Custom Gecko-family binary path. system default
--starting-url <url> - Starting URL in launched browser. unset
--no-runner - Skip browser launch. runner enabled
--port <port> - Runner/devtools port when runner is enabled. 8080
--extensions <list> - Comma-separated companion extensions or store URLs. unset
--author --author-mode Enable maintainer diagnostics. disabled

Logging flags

Flag What it does Default
--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-timestamps Disable timestamps in pretty mode. timestamps enabled
--no-log-color Disable 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)

preview accepts these flags in parsing, but exits with an error if you use them. Use dev --source ... instead.

Flag Support 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

Video demo soon: preview command local artifact flow

npm
pnpm
yarn
extension preview ./my-extension

Previewing in Edge and Chrome

Video demo soon: preview multi-browser validation

npm
pnpm
yarn
extension preview ./my-extension --browser=edge,chrome

Preview without launching browser

Video demo soon: preview no-runner flow

npm
pnpm
yarn
extension preview ./my-extension --no-runner

Important behavior notes

  • preview expects an existing build output (dist/<browser> by default).
  • preview does not run watch/HMR.
  • Source inspection flags are not supported in preview; use dev for that workflow.

Best practices

  • Run build before preview when testing a fresh production artifact.
  • Use --browser to verify behavior across targets before packaging.

Next steps

ON THIS PAGE