ImageBoss Elixir

Elixir client for generating ImageBoss image URLs. ImageBoss resizes, compresses, and delivers your images through a global CDN via URL parameters.

Documentation

Installation

Add imageboss to your list of dependencies in mix.exs:

def deps do
  [
    {:imageboss, "~> 0.5"}
  ]
end

Usage

Create a client with your ImageBoss source name (from your dashboard):

client = Imageboss.new(source: "mywebsite-images")

Operations

Cover (crop to exact width and height):

Imageboss.url(client, "/images/photo.jpg", :cover, width: 300, height: 300)
#=> "https://img.imageboss.me/mywebsite-images/cover/300x300/images/photo.jpg"

Width (fixed width, proportional height):

Imageboss.url(client, "/images/photo.jpg", :width, width: 700)

Height (fixed height, proportional width):

Imageboss.url(client, "/images/photo.jpg", :height, height: 400)

CDN (deliver through CDN without resizing):

Imageboss.url(client, "/images/photo.jpg", :cdn)

Cover options

Extra options (all operations)

Pass options: ["key:value", ...] for filters and options (grayscale, format, download, etc.) as per ImageBoss docs.

Disabled mode (dev/test)

When you don't want to send images through ImageBoss (e.g. in tests or local dev), disable URL generation:

client = Imageboss.new(source: "mywebsite", disabled: true)
Imageboss.url(client, "/images/photo.jpg", :width, width: 100)
#=> "/images/photo.jpg"

Signed URLs

If your source has signed URLs enabled, pass your secret:

client = Imageboss.new(source: "mywebsite", secret: "your-secret-token")
Imageboss.url(client, "/images/photo.jpg", :width, width: 100)
#=> "https://img.imageboss.me/mywebsite/width/100/images/photo.jpg?bossToken=..."

Playground

Run the included Livebook notebook with the Livebook escript (requires Elixir 1.18+).

One-time install (from this project directory so the right Elixir is used):

mix escript.install hex livebook

Start the playground (this is the livebook executable, not a Mix task—do not use mix).

asdf does not add Mix escripts to PATH; the binary lives in your Elixir install under .mix/escripts/. Run it with the full path:

To have livebook on PATH, add the escripts directory to your shell config (after asdf is loaded):

Then you can run livebook server imageboss_playground.livemd from anywhere.

Open the URL shown (e.g. http://localhost:8080). You can also open imageboss_playground.livemd in Livebook Desktop or the VS Code Livebook extension.

Testing

mix test

Releasing a new version and publishing to Hex

Use the release script from the project root:

# Bump patch, run tests, and print next steps
mix run script/release.exs

# Bump minor or major
mix run script/release.exs minor
mix run script/release.exs major

# Set exact version
mix run script/release.exs 1.2.3

# Dry run (only bump version in mix.exs and run tests; no commit/tag/publish)
DRY_RUN=1 mix run script/release.exs

Prerequisites:

License

MIT