PhoenixImage

An on-demand image optimization library for Phoenix applications. phx_image provides a Plug that fetches source images, resizes/transcodes them, and serves them with caching headers. It also provides a Next.js-like <.image /> function component for Phoenix templates.

Features

On-Demand Optimization: Fetch, resize, and convert images on the fly via HTTP.
Aspect-Preserving Resizing: Keep original aspect ratio while fitting requested dimensions.
Multiple Formats: Supports outputting as webp, avif, jpg, and png.
High Performance: Powered by libvips via the image library for extremely fast processing.
Built-in Caching Headers: Automatically sets Cache-Control headers for long-term browser caching.

Installation

The package can be installed by adding phx_image to your list of dependencies in mix.exs:

def deps do
  [
    {:phx_image, "~> 0.1.0"}
  ]
end

PhoenixImage.Component depends on :phoenix_live_view. Add it explicitly if you use the component:

def deps do
  [
    {:phx_image, "~> 0.1.0"},
    {:phoenix_live_view, "~> 1.0"}
  ]
end

Usage

Demo App

This repo includes a Phoenix demo app in demo/ for manual testing.

cd demo
mix deps.get
mix phx.server

Open http://localhost:4000 and use the form to test /images/optimize.

As a Plug

You can mount the PhoenixImage.Plug in your Phoenix router or as part of a standalone Plug pipeline:

# In your router.ex
scope "/images" do
  pipe_through :browser
  get "/optimize", PhoenixImage.Plug, []
end

As a Component (`<.image />`)

Add to your Phoenix components module:

defmodule MyAppWeb.CoreComponents do
  use Phoenix.Component
  import PhoenixImage.Component, only: [image: 1]
end

Use in HEEx:

<.image
  src="https://example.com/photo.jpg"
  alt="Scenic view"
  width={1200}
  height={800}
  sizes="100vw"
/>

Required sizing rule:

fill={true} OR both width and height.

Configure component defaults:

config :phx_image, :image_component,
  optimize_path: "/images/optimize",
  device_sizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  image_sizes: [16, 32, 48, 64, 96, 128, 256, 384],
  allowed_hosts: ["example.com", "cdn.example.com"]

Plug Options

PhoenixImage.Plug supports:

:cache_control (default: public, max-age=31536000, immutable)
:allowed_hosts (default: []): extra hosts allowed for absolute src URLs in addition to the request host.

Query Parameters

src (required): source image location.
- Absolute http:// or https:// URL, or
- Root-relative path like /images/logo.png (resolved against request host).
w (optional): positive integer width, max 8192.
h (optional): positive integer height, max 8192.
q (optional): quality from 1 to 100.
f (optional): output format webp|avif|jpg|png. Default: webp.
upscale (optional): true|false. Default: false.

Resize Behavior

w only: scales to width, preserves aspect ratio.
h only: scales to height, preserves aspect ratio.
w + h: fits inside the box while preserving aspect ratio (does not crop to exact dimensions).
By default, requests that would enlarge the image are clamped to source size.
With upscale=true, enlarge is allowed up to 2x source size.

Example

Requesting a 400px wide WebP version of an external image:

GET /images/optimize?src=https://example.com/large-photo.jpg&w=400&f=webp

The response will include:

The processed image binary.
Content-Type: image/webp.
Cache-Control: public, max-age=31536000, immutable.
x-phoenix-image-upscale: skipped when a requested enlargement was clamped.

Relative `src` Example

GET /images/optimize?src=/images/logo.png&w=320

Error Semantics

400 Bad Request: missing/invalid parameters.
403 Forbidden: src host is not same-host and not in :allowed_hosts.
404 Not Found: upstream source returned 404.
500 Internal Server Error: upstream/image-processing failures.

Requirements

libvips: This library requires libvips to be installed on your system.
- macOS: brew install vips
- Linux: apt install libvips-dev (or equivalent for your distribution)

Compatibility

Elixir ~> 1.15
Plug ~> 1.19
Optional component dependency: phoenix_live_view ~> 1.0
System dependency: libvips with desired output codecs (webp, avif, etc.)

Security Notes

Validate src inputs and restrict with :allowed_hosts for remote fetches.
Avoid exposing unrestricted optimizer endpoints on untrusted networks.

License

Apache-2.0. See LICENSE.

Documentation can be generated locally with:

mix docs

Docs are published automatically to GitLab Pages from the default branch.

Releasing

Use the custom task to run preflight checks, tag, push, and publish:

mix release.publish --yes

Useful flags:

--no-publish: run checks and create/push tag without publishing to Hex.
--no-tag: publish without creating a tag.
--no-push: avoid pushing HEAD and tag.
--skip-precommit: skip mix precommit.
--remote origin: choose push remote.

Next Page → LICENSE