Preview command

    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, but it can also run from another unpacked extension directory if that directory already contains a manifest.json.

    Usage

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

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

    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 directory
    3. --output-path when you explicitly point to an unpacked extension root

    What matters is not whether a build happened in the same command. What matters is whether the chosen directory already contains an unpacked extension with a manifest.json.

    Core options

    FlagAliasWhat it doesDefault
    [path]-Preview built extension from a project path.process.cwd()
    --browser <browser>-bBrowser/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.8080
    --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)

    preview accepts these flags in parsing, but exits with an error if you use them. 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

    npm
    pnpm
    yarn
    extension preview ./my-extension

    Previewing in Edge and Chrome

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

    Preview without launching browser

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

    Important 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/HMR.
    • Source inspection flags are not supported in preview; 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 --output-path when your unpacked extension lives outside the default project output.
    • Use --browser to verify behavior across targets before packaging.

    Next steps