# LightpandaEx

[![CI](https://github.com/mattneel/lightpanda_ex/actions/workflows/main.yml/badge.svg)](https://github.com/mattneel/lightpanda_ex/actions/workflows/main.yml)

Mix tasks for installing and invoking the
[Lightpanda](https://github.com/lightpanda-io/browser) headless browser.

LightpandaEx follows the same shape as the Phoenix-maintained `esbuild`
package: it downloads a platform-specific executable into `_build`, exposes a
Mix install task, and lets you define named execution profiles in
`config/config.exs`.

The default tracked Lightpanda binary is `0.3.0`.

## Installation

If you are going to run Lightpanda in production, add `lightpanda_ex` as a
dependency in all environments but only start it in development:

```elixir
def deps do
  [
    {:lightpanda_ex, "~> 0.1", runtime: Mix.env() == :dev}
  ]
end
```

If Lightpanda is only used during development, make it a dev-only dependency:

```elixir
def deps do
  [
    {:lightpanda_ex, "~> 0.1", only: :dev}
  ]
end
```

Then configure the Lightpanda release in `config/config.exs`:

```elixir
config :lightpanda_ex, version: "0.3.0"
```

Install the binary:

```bash
$ mix lightpanda.install
```

The executable is kept at `_build/lightpanda-TARGET`, where `TARGET` is your
system target architecture, such as `x86_64-linux` or `aarch64-macos`.

## Quick start

LightpandaEx ships with a built-in `:default` profile that starts a CDP server
on `127.0.0.1:9222`:

```bash
$ mix lightpanda default
```

This runs:

```bash
lightpanda serve --host 127.0.0.1 --port 9222
```

## Profiles

The first argument to `mix lightpanda` is the execution profile. Profiles are
configured in `config/config.exs` and can set:

  * `:args` - arguments passed to the Lightpanda binary
  * `:cd` - the working directory
  * `:env` - environment variables

For example, define a profile that dumps a page to markdown:

```elixir
config :lightpanda_ex,
  version: "0.3.0",
  dump: [
    args: ~w(fetch --obey-robots --dump markdown),
    env: %{"LIGHTPANDA_DISABLE_TELEMETRY" => "true"}
  ]
```

Then run:

```bash
$ mix lightpanda dump https://example.com
```

Arguments passed to the Mix task are appended to the configured profile
arguments.

Profiles must be configured in `config/config.exs`. The Mix tasks load config
without starting your application, so they will not pick up settings from
`config/runtime.exs` unless you pass `--runtime-config`.

## Dump a URL

Configure a profile:

```elixir
config :lightpanda_ex,
  version: "0.3.0",
  dump: [
    args: ~w(fetch --obey-robots --dump markdown --log-format pretty --log-level info),
    env: %{"LIGHTPANDA_DISABLE_TELEMETRY" => "true"}
  ]
```

Then invoke it with a URL:

```bash
$ mix lightpanda dump https://demo-browser.lightpanda.io/campfire-commerce/
```

## Start a CDP server with a custom profile

Configure a profile:

```elixir
config :lightpanda_ex,
  version: "0.3.0",
  serve: [
    args: ~w(serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222),
    env: %{"LIGHTPANDA_DISABLE_TELEMETRY" => "true"}
  ]
```

Then start Lightpanda:

```bash
$ mix lightpanda serve
```

Once the CDP server is started, you can connect a Puppeteer or Playwright
client to `ws://127.0.0.1:9222`.

## Release tracking

By default, LightpandaEx installs the configured `:version`:

```elixir
config :lightpanda_ex, version: "0.3.0"
```

You can also track Lightpanda nightly builds:

```elixir
config :lightpanda_ex, release: "nightly"
```

For stable releases, LightpandaEx tries both tag styles because upstream
Lightpanda releases have used both `0.3.0` and `v0.2.6`-style tags.

## Custom download URL or mirror

The default binary URL template is:

```text
https://github.com/lightpanda-io/browser/releases/download/$version/lightpanda-$target
```

You can override it with a mirror or local cache:

```elixir
config :lightpanda_ex,
  url: "https://my-mirror.example.com/lightpanda/$version/lightpanda-$target"
```

The `$version` placeholder receives the configured release (`0.3.0`,
`v0.2.6`, or `nightly`). The `$target` placeholder receives the detected
platform target.

## Manual binary path

If you manage Lightpanda outside this package, set `:path`:

```elixir
config :lightpanda_ex, path: System.get_env("MIX_LIGHTPANDA_PATH")
```

You can disable the boot-time version warning when using an external binary:

```elixir
config :lightpanda_ex, version_check: false
```

## Supported targets

LightpandaEx supports the binary targets published by Lightpanda:

  * `x86_64-linux`
  * `aarch64-linux`
  * `x86_64-macos`
  * `aarch64-macos`

Lightpanda does not publish a native Windows binary. Use WSL2 and the Linux
binary on Windows.

## Checksums

LightpandaEx verifies SHA-256 checksums for the tracked stable release
(`0.3.0`). Checksums are skipped with a warning for custom versions or nightly
builds that are not known to this package version.

## Telemetry

By default, Lightpanda collects and sends usage telemetry. You can disable this
by setting `LIGHTPANDA_DISABLE_TELEMETRY=true` in the profile `:env`.

## API

The public module is `LightpandaEx`:

```elixir
LightpandaEx.install()
LightpandaEx.install_and_run(:default, [])
LightpandaEx.run(:dump, ["https://example.com"])
LightpandaEx.bin_path()
LightpandaEx.bin_version()
```

## License

Copyright (c) 2026 Matthew Neel.

The LightpandaEx package source code is licensed under the
[MIT License](LICENSE.md).

Lightpanda Browser is licensed separately by the upstream project under the
[GNU Affero General Public License v3.0](https://github.com/lightpanda-io/browser/blob/main/LICENSE).