# `LightpandaEx`
[🔗](https://github.com/mattneel/lightpanda_ex/blob/v0.1.0/lib/lightpanda_ex.ex#L1)

LightpandaEx is an installer and runner for the
[Lightpanda](https://github.com/lightpanda-io/browser) headless browser.

## Configuration

Configure in your `config/config.exs`:

    config :lightpanda_ex,
      version: "0.3.0",
      default: [
        args: ~w(serve --host 127.0.0.1 --port 9222)
      ]

## Global options

  * `:version` - the expected Lightpanda version. Defaults to
    `0.3.0`.

  * `:path` - the path to the Lightpanda binary. By default it is
    automatically downloaded and placed inside the `_build` directory.

  * `:release` - which release to track. Either a version string like
    `"0.3.0"` (default, derived from `:version`) or `"nightly"`
    to track the nightly build.

  * `:url` - the base URL template to download the binary from.
    Defaults to `Elixir.LightpandaEx.default_base_url/0`. Supports the
    placeholders `$version` and `$target`, for example:

        "https://my-mirror.example.com/lightpanda/$version/lightpanda-$target"

  * `:version_check` - set to `false` to skip the boot-time check
    that warns when the installed binary's version doesn't match the
    configured `:version`. Defaults to `true`.

## Profiles

Each profile accepts:

  * `:args` - arguments to pass to the Lightpanda binary.
  * `:cd` - the working directory.
  * `:env` - environment variables as a map of string key/value pairs.

The built-in `:default` profile starts a CDP server on `127.0.0.1:9222`.

# `bin_path`

Returns the path to the Lightpanda binary.

# `bin_version`

Returns the version of the installed Lightpanda binary.

Returns `{:ok, version_string}` on success or `:error` when the executable
is not available.

# `config_for!`

Returns the configuration for the given profile.

# `configured_version`

Returns the configured version of the Lightpanda binary.

# `default_base_url`

Returns the default URL template used to fetch the binary.

Supports the `$version` and `$target` placeholders. Configure
`config :lightpanda_ex, :url, "..."` to redirect downloads to a mirror
or local cache.

# `ensure_installed!`

Ensures the Lightpanda binary is installed.

Concurrent callers are deduplicated so parallel `install_and_run/2`
invocations only download once.

# `install`

Installs the configured Lightpanda binary.

This downloads `configured_version/0` by default. Configure `:release` to
`"nightly"` to track Lightpanda nightly builds instead.

# `install_and_run`

Installs the binary if missing, then runs it with the given profile and extra arguments.

Returns the exit status.

# `latest_version`

Returns the latest known version of the Lightpanda binary.

# `run`

Runs the Lightpanda binary with the given profile and extra arguments.

The given arguments are appended to the configured profile arguments.
Output is streamed directly to stdio, and the return value is the exit status.

# `target`

Returns the platform target string, for example `"x86_64-linux"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*