Configuration

Plushie is configured at three levels: environment variables for deployment and CI, application config for project-wide defaults, and runtime options on Plushie.start_link/2 for per-instance control. Most projects need minimal configuration. Build or download the binary and go.

Environment variables

PLUSHIE_BINARY_PATH

Forces a specific renderer binary. Useful in CI where the binary is pre-built and stored at a known path, or in production deployments where the binary ships alongside the release. If set but pointing to a missing file, resolution raises immediately rather than falling through to other paths.

PLUSHIE_SOURCE_PATH

Points to a local checkout of the plushie-renderer repository. When set, mix plushie.build uses local path dependencies instead of crates.io, and the dev server watches .rs files for hot reload. The typical setup is a sibling directory:

git clone https://github.com/plushie-ui/plushie-renderer ../plushie-renderer
PLUSHIE_SOURCE_PATH=../plushie-renderer mix plushie.build

RUST_LOG

Controls the renderer's log output using the standard env_logger format. The Bridge forwards this to the renderer process at startup. Common values:

• plushie=debug - full protocol and rendering detail
• plushie=info - connection events and major state changes
• plushie=warn - warnings only (default-like)

When RUST_LOG is set, the :log_level option on start_link/2 is ignored. Combine with --json for full wire protocol visibility:

RUST_LOG=plushie=debug mix plushie.gui MyApp --json

Application config

Set in config/*.exs under config :plushie. A typical development setup looks like this:

# config/dev.exs
import Config

config :plushie, code_reloader: true

Most projects only need :code_reloader in dev. The remaining options are for customising builds, binary paths, and test backends.

Binary and build

Development

Code reloader options

When :code_reloader is set to a keyword list, these options are supported:

Rust file changes (.rs, Cargo.toml) use a separate debounce of 200ms (not configurable) because Cargo builds are heavier and benefit from more coalescing.

Runtime options (start_link/2)

Plushie.start_link/2 starts a Plushie application. The first argument is the app module (implementing Plushie.App), and the second is an optional keyword list of options:

Plushie.start_link(MyApp, binary: Plushie.Binary.path!(), daemon: true)

Common options

Transport

Advanced

App settings callback

The optional Plushie.App.settings/0 callback provides application-level defaults to the renderer at startup. These are sent once during the initial handshake and affect all windows.

defmodule MyApp do
  use Plushie.App
  import Plushie.UI

  def settings do
    [
      default_text_size: 16,
      theme: :dark,
      fonts: ["priv/fonts/inter.ttf"],
      default_event_rate: 60
    ]
  end

  def init(_opts), do: %{}
  def update(model, _event), do: model

  def view(_model) do
    window "main", title: "MyApp" do
      text("hello", "Hello")
    end
  end
end

Widget discovery

Native widgets are auto-detected via Plushie.Widget.WidgetProtocol protocol consolidation at compile time. Any module that implements the protocol and exports native_crate/0 is included in mix plushie.build automatically.

Plushie.WidgetRegistry exposes the discovered widgets. No configuration is needed. Add a native widget to your dependencies and it appears in the next build.

Pure Elixir widgets (those with view/2 or view/3 callbacks) do not require protocol consolidation or build system integration. They work with any renderer binary, including precompiled downloads.

Transport modes

The renderer communicates with the SDK over a language-agnostic wire protocol (MessagePack or JSON over a byte stream). The SDK supports three transport modes:

:spawn (default)

The SDK spawns the renderer as a child process via an Erlang Port. Communication happens over the process's stdin/stdout. This is the default for local development. mix plushie.gui uses this mode.

The Bridge manages the Port lifecycle: starting, monitoring, and restarting the renderer on crash (with exponential backoff). The renderer process inherits RUST_LOG from the environment.

:stdio

The renderer spawns the Elixir app (via plushie --exec "mix ..."). Communication happens over the BEAM's own stdin/stdout. The Elixir app reads events from stdin and writes snapshots/patches to stdout.

This mode is used by the renderer's --exec flag, which starts the renderer first, then launches the Elixir app as a subprocess. The :binary option is ignored since no subprocess is spawned from the Elixir side.

### {:iostream, pid}

A message-based adapter for custom transports. The pid is a process that bridges between the wire protocol and an arbitrary transport (SSH channel, TCP socket, Unix socket, WebSocket, etc.).

The adapter process must handle these messages:

The adapter is responsible for framing, splitting the byte stream into complete protocol messages before sending {:iostream_data, ...}. Plushie.Transport.Framing provides frame encode/decode for length-prefixed byte streams (the standard wire framing).

This mode enables remote rendering: the Elixir app runs on one machine (server, embedded device, cloud), the renderer runs on another (desktop, laptop, mobile). The wire protocol is identical; only the transport layer differs. See the Shared State guide for a complete SSH example.

Test configuration

Plushie.Test.setup!/1 accepts options for the test session pool:

The test backend is selected via the PLUSHIE_TEST_BACKEND environment variable or config :plushie, :test_backend. See the Testing reference for backend setup and CI configuration.

See also

• Mix Tasks reference - binary resolution, build options, and all task flags
• Wire Protocol reference - message formats and framing details
• Testing reference - test backends and session pool
• Plushie.Binary - binary resolution logic and version
• Plushie.Bridge - transport management and restart behaviour
• Plushie.WidgetRegistry - widget discovery at compile time
• Plushie.App - the full callback specification including settings/0