Documentation Index
Fetch the complete documentation index at: https://extension.js.org/llms.txt
Use this file to discover all available pages before exploring further.
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
| 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 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.
extension preview [project-path] [options]
How preview chooses what to run
preview checks these locations in order:
dist/<browser> for the selected browser target.- 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
| Flag | Alias | What it does | Default |
|---|
[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-binary | Custom 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-mode | Enable maintainer diagnostics. | disabled |
preview writes readiness metadata to:
dist/extension-js/<browser>/ready.json
For --no-browser flows, this provides deterministic command state:
starting while command initializesready when run-only validation is completeerror when required output is missing or startup failsrunId 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
| 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)
The CLI detects these flags and exits with an error before parsing. 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
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
