PhoenixAssets (PhoenixAssets v0.1.0)

Runtime and generated contracts for Phoenix applications built with Vite.

phoenix_assets supervises Vite and Storybook in development, generates typed frontend contracts from Phoenix and Ash, links routes, pages, stories, sync shapes, PubSub topics, and locales in an asset graph, and validates the production manifest. It does not bundle assets itself or require LiveView as the application's UI layer.

This module provides the runtime API. Related modules include:

PhoenixAssets.Config -- normalized, validated configuration.
PhoenixAssets.Preset / PhoenixAssets.Plugin -- the integration engine.
PhoenixAssets.Generated -- the contract generators (routes, types, ...).
PhoenixAssets.Manifest / PhoenixAssets.ManifestServer -- Vite manifest.
PhoenixAssets.Graph -- the asset graph.
PhoenixAssets.DevSupervisor -- supervised dev processes.
PhoenixAssets.Doctor -- configuration and production validation.

Platform support

Development supervision -- Vite and Storybook as OS children with process-group teardown -- requires a POSIX platform (macOS, Linux, or WSL2), because it relies on MuonTrap, which is POSIX-only. Production manifest serving and contract generation are platform-independent.

Summary

Functions

asset_path(key)

Returns the served path for an asset key.

child_specs(opts \\ [])

The supervised children a host application adds to its own tree.

dev?()

Whether development features (supervised Vite/Storybook, the dev overlay, the generated-file watcher) are active.

entry!(key)

Resolves an entry to its production assets, or :dev in development.

graph()

Loads the asset graph (graph.json), or an empty map if none has been built.

page!(name)

Fetches a page from the asset graph by name, raising if absent.

route!(name)

Fetches a route from the asset graph by name, raising if absent.

version()

The installed version of phoenix_assets.

vite_dev_url(path)

Builds a Vite dev-server URL for path.

Functions

asset_path(key)

@spec asset_path(String.t()) :: String.t()

Returns the served path for an asset key.

In production resolves to the hashed file from the manifest (prefixed with the configured :asset_url, if any). In development returns the key as a root-relative path (the Vite dev server serves it). Raises if a manifest is expected but unavailable.

child_specs(opts \\ [])

@spec child_specs(keyword()) :: [Supervisor.child_spec() | {module(), term()}]

The supervised children a host application adds to its own tree.

Always includes PhoenixAssets.ManifestServer; in development also includes PhoenixAssets.DevSupervisor (Vite, Storybook, the generated-file watcher). Add them in your Application.start/2:

children = [
  # ... your children ...
] ++ PhoenixAssets.child_specs()

Options:

:config -- a PhoenixAssets.Config (defaults to PhoenixAssets.Config.load!/1).
:ctx -- a prebuilt PhoenixAssets.Context (defaults to one derived from the config and the configured preset).

dev?()

@spec dev?() :: boolean()

Whether development features (supervised Vite/Storybook, the dev overlay, the generated-file watcher) are active.

Defaults to false so production never spawns dev processes. Enable with:

config :phoenix_assets, :dev, enabled: true

entry!(key)

@spec entry!(String.t()) ::
  %{
    file: String.t(),
    css: [String.t()],
    imports: [String.t()],
    integrity: %{required(String.t()) => String.t()}
  }
  | :dev

Resolves an entry to its production assets, or :dev in development.

In production returns %{file:, css:, imports:, integrity:} from the Vite manifest (integrity is a possibly-empty href => hash map, populated only when the manifest carries SRI metadata). When config :phoenix_assets, :build, asset_url: "https://cdn.example.com" is set, every href (including the integrity keys) is prefixed with it. In development returns :dev so callers emit dev-server URLs. Raises if a manifest is expected but unavailable.

graph()

@spec graph() :: map()

Loads the asset graph (graph.json), or an empty map if none has been built.

For hot paths, prefer a module built with PhoenixAssets.Graph.Compiled.

page!(name)

@spec page!(String.t()) :: map()

Fetches a page from the asset graph by name, raising if absent.

route!(name)

@spec route!(String.t()) :: map()

Fetches a route from the asset graph by name, raising if absent.

version()

@spec version() :: String.t()

The installed version of phoenix_assets.

vite_dev_url(path)

@spec vite_dev_url(String.t()) :: String.t()

Builds a Vite dev-server URL for path.

Prefers the hot file the Vite plugin writes (.phoenix-assets/hot under the asset root, carrying the server's actual resolved URL -- scheme, host, and port included, so HTTPS dev servers work); falls back to the configured dev: [vite: [host:, port:]].