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

# Preview command to launch built extensions

> Launch an already-built extension for production-like manual testing without recompiling. Load unpacked output and run the browser launcher flow.

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

## Usage

<CodeGroup>
  ```bash npm theme={null}
  extension preview [project-path] [options]
  ```

  ```bash pnpm theme={null}
  extension preview [project-path] [options]
  ```

  ```bash yarn theme={null}
  extension preview [project-path] [options]
  ```

  ```bash bun theme={null}
  extension preview [project-path] [options]
  ```

  ```bash bun theme={null}
  extension preview [project-path] [options]
  ```
</CodeGroup>

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

| 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](/docs/browsers/running-other-browsers). | system default         |
| `--gecko-binary <path>`     | `--firefox-binary` | [Custom Gecko-family binary path](/docs/browsers/running-other-browsers).    | 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               |

## 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

| 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](/docs/workflows/global-flags).

## Examples

### Previewing a local extension

<CodeGroup>
  ```bash npm theme={null}
  extension preview ./my-extension
  ```

  ```bash pnpm theme={null}
  extension preview ./my-extension
  ```

  ```bash yarn theme={null}
  extension preview ./my-extension
  ```

  ```bash bun theme={null}
  extension preview ./my-extension
  ```

  ```bash bun theme={null}
  extension preview ./my-extension
  ```
</CodeGroup>

### Previewing in Edge and Chrome

<CodeGroup>
  ```bash npm theme={null}
  extension preview ./my-extension --browser=edge,chrome
  ```

  ```bash pnpm theme={null}
  extension preview ./my-extension --browser=edge,chrome
  ```

  ```bash yarn theme={null}
  extension preview ./my-extension --browser=edge,chrome
  ```

  ```bash bun theme={null}
  extension preview ./my-extension --browser=edge,chrome
  ```

  ```bash bun theme={null}
  extension preview ./my-extension --browser=edge,chrome
  ```
</CodeGroup>

### Preview without launching the browser

<CodeGroup>
  ```bash npm theme={null}
  extension preview ./my-extension --no-browser
  ```

  ```bash pnpm theme={null}
  extension preview ./my-extension --no-browser
  ```

  ```bash yarn theme={null}
  extension preview ./my-extension --no-browser
  ```

  ```bash bun theme={null}
  extension preview ./my-extension --no-browser
  ```

  ```bash bun theme={null}
  extension preview ./my-extension --no-browser
  ```
</CodeGroup>

## 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

* Build and launch in one step with [`start`](/docs/commands/start).
* Generate production artifacts with [`build`](/docs/commands/build).
* Configure shared defaults in [`extension.config.js`](/docs/features/extension-configuration).
* Review configuration env loading behavior in [Environment variables](/docs/features/environment-variables#how-it-works).