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

# Start command for build-and-launch workflow

> Run a production build and immediately launch the extension in the browser with one command. Combines build and preview into a single step.

Use `start` when you want a production build and immediate browser launch in one command.

The `start` command runs a production build first, then launches the built extension using the same flow as the `preview` command.

## When to use `start`

* Manually validating production behavior right after compilation.
* Reproducing runtime differences between watch mode and production output.
* Running a production-like check locally without a separate `build` then `preview` step.

## Start command capabilities

| Capability                 | What it gives you                                         |
| -------------------------- | --------------------------------------------------------- |
| Build + launch workflow    | Run production compile and browser launch in one step     |
| Target selection           | Start directly in selected browser or engine target       |
| Runner control             | Skip browser launch when you only need build verification |
| Production-like validation | Check real compiled output instead of watch-mode state    |

## How it differs from other commands

* `dev`: dev server + hot module replacement (HMR)/watch mode
* `build`: production build only
* `preview`: launch an existing built extension without building
* `start`: `build` + `preview` in sequence

## Usage

<CodeGroup>
  ```bash npm theme={null}
  extension start [path-or-url] [options]
  ```

  ```bash pnpm theme={null}
  extension start [path-or-url] [options]
  ```

  ```bash yarn theme={null}
  extension start [path-or-url] [options]
  ```

  ```bash bun theme={null}
  extension start [path-or-url] [options]
  ```

  ```bash deno theme={null}
  extension start [path-or-url] [options]
  ```
</CodeGroup>

If you omit the path, the command uses the current working folder.

## Arguments and flags

| Flag                           | Alias              | What it does                                                                                      | Default                                         |
| ------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `[path or url]`                | -                  | Extension path or remote URL.                                                                     | `process.cwd()`                                 |
| `--browser <browser>`          | -                  | Browser/engine target.                                                                            | `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                                  |
| `--polyfill [boolean]`         | -                  | Enable `browser.*` API compatibility polyfill for Chromium targets.                               | `true`                                          |
| `--starting-url <url>`         | -                  | Starting URL in launched browser.                                                                 | unset                                           |
| `--no-browser`                 | -                  | Build but skip browser launch.                                                                    | browser launch enabled                          |
| `--wait [boolean]`             | -                  | Wait for `dist/extension-js/<browser>/ready.json` and exit.                                       | disabled                                        |
| `--wait-timeout <ms>`          | -                  | Timeout for `--wait` mode.                                                                        | `60000`                                         |
| `--wait-format <pretty\|json>` | -                  | Output format for wait results (`json` is machine-readable).                                      | `pretty`                                        |
| `--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`                                     |
| `--public-host <host>`         | -                  | Connectable host the browser dials when it differs from the bind `--host` (remote/dev container). | bind host (`127.0.0.1` when bound to `0.0.0.0`) |
| `--extensions <list>`          | -                  | Comma-separated companion extensions or store URLs.                                               | unset                                           |
| `--install [boolean]`          | -                  | Install project dependencies when missing.                                                        | command behavior default                        |
| `--author`                     | `--author-mode`    | Enable maintainer diagnostics.                                                                    | disabled                                        |

## Automation metadata

`start` writes readiness metadata to:

* `dist/extension-js/<browser>/ready.json`

This is useful for automation when using `--no-browser`:

* Wait for `status: "ready"` before launching external runners.
* Handle `status: "error"` as a deterministic failure signal.
* Use `runId` and `startedAt` to correlate a specific runtime session.

### `--no-browser` and readiness synchronization

`--no-browser` only disables browser launch. It does not block external runners until the production build finishes.

For production-oriented Playwright, continuous integration (CI), and AI workflows:

1. Run `extension start --no-browser` as the producer process.
2. Run `extension start --wait --browser=<browser>` as the readiness gate.
3. Launch external browser automation only after `status: "ready"`.

`--wait` exits non-zero on `error`/timeout and ignores stale contracts from dead processes (`pid` no longer alive).
If you pass both `--wait` and `--no-browser` in the same invocation, `--wait` takes precedence. The command runs in wait-only mode.

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

## Shared global options

Also supports [Global flags](/docs/workflows/global-flags).

## Examples

### Start with default browser

<CodeGroup>
  ```bash npm theme={null}
  extension start
  ```

  ```bash pnpm theme={null}
  extension start
  ```

  ```bash yarn theme={null}
  extension start
  ```

  ```bash bun theme={null}
  extension start
  ```

  ```bash deno theme={null}
  extension start
  ```
</CodeGroup>

### Start in Firefox

<CodeGroup>
  ```bash npm theme={null}
  extension start --browser firefox
  ```

  ```bash pnpm theme={null}
  extension start --browser firefox
  ```

  ```bash yarn theme={null}
  extension start --browser firefox
  ```

  ```bash bun theme={null}
  extension start --browser firefox
  ```

  ```bash deno theme={null}
  extension start --browser firefox
  ```
</CodeGroup>

### Build and skip browser launch

<CodeGroup>
  ```bash npm theme={null}
  extension start --no-browser
  ```

  ```bash pnpm theme={null}
  extension start --no-browser
  ```

  ```bash yarn theme={null}
  extension start --no-browser
  ```

  ```bash bun theme={null}
  extension start --no-browser
  ```

  ```bash deno theme={null}
  extension start --no-browser
  ```
</CodeGroup>

## Behavior notes

* `start` does not run a dev server and does not provide hot module replacement (HMR) or watch mode.
* `start` is production-mode oriented; use `dev` for iterative local development.
* For machine consumers, parse `dist/extension-js/<browser>/ready.json` instead of terminal text.

## Next steps

* Iterate quickly with [`dev`](/docs/commands/dev).
* Launch existing build output with [`preview`](/docs/commands/preview).