🖼️ IPX

Note

This is the active development branch. Check out v2 and v3 for older docs.

High performance, secure and easy-to-use image optimizer powered by sharp and svgo.

Used by Nuxt Image and Netlify and open to everyone!

Using CLI

You can use ipx command to start server.

Using npx:

npx ipx serve --dir ./

Using bun

bun x npx ipx serve --dir ./

The default serve directory is the current working directory.

Programmatic API

You can use IPX as a middleware or directly use IPX interface.

import { createIPX, ipxFSStorage, ipxHttpStorage } from "ipx";

const ipx = createIPX({
  storage: ipxFSStorage({ dir: "./public" }),
  httpStorage: ipxHttpStorage({ domains: ["picsum.photos"] }),
});

Example: Using with unjs/h3:

import { listen } from "listhen";
import { createApp, toNodeListener } from "h3";
import {
  createIPX,
  ipxFSStorage,
  ipxHttpStorage,
  createIPXH3Handler,
} from "ipx";

const ipx = createIPX({
  storage: ipxFSStorage({ dir: "./public" }),
  httpStorage: ipxHttpStorage({ domains: ["picsum.photos"] }),
});

const app = createApp().use("/", createIPXH3Handler(ipx));

listen(toNodeListener(app));

Example: Using express:

import { listen } from "listhen";
import express from "express";
import {
  createIPX,
  ipxFSStorage,
  ipxHttpStorage,
  createIPXNodeServer,
} from "ipx";

const ipx = createIPX({
  storage: ipxFSStorage({ dir: "./public" }),
  httpStorage: ipxHttpStorage({ domains: ["picsum.photos"] }),
});

const app = express().use("/", createIPXNodeServer(ipx));

listen(app);

URL Examples

Get original image:

/_/static/buffalo.png

Change format to webp and keep other things same as source:

/f_webp/static/buffalo.png

Automatically convert to a preferred format (avif/webp/jpeg). Uses the browsers accept header to negotiate:

/f_auto/static/buffalo.png

Keep original format (png) and set width to 200:

/w_200/static/buffalo.png

Resize to 200x200px using embed method and change format to webp:

/embed,f_webp,s_200x200/static/buffalo.png

Config

You can universally customize IPX configuration using IPX_* environment variables.

IPX_ALIAS
- Default: {}

Filesystem Source Options

(enabled by default with CLI only)

`IPX_FS_DIR`

Default: . (current working directory)

`IPX_FS_MAX_AGE`

Default: 300

HTTP(s) Source Options

(enabled by default with CLI only)

`IPX_HTTP_DOMAINS`

Default: []

`IPX_HTTP_MAX_AGE`

Default: 300

`IPX_HTTP_FETCH_OPTIONS`

Default: {}

`IPX_HTTP_ALLOW_ALL_DOMAINS`

Default: false

Modifiers

Property	Docs	Example	Comments
width / w	Docs	`/width_200/buffalo.png` or `/w_200/buffalo.png`
height / h	Docs	`/height_200/buffalo.png` or `/h_200/buffalo.png`
resize / s	Docs	`/s_200x200/buffalo.png`
kernel	Docs	`/s_200x200,kernel_nearest/buffalo.png`	Supported kernel: `nearest`, `cubic`, `mitchell`, `lanczos2` and `lanczos3` (default).
fit	Docs	`/s_200x200,fit_outside/buffalo.png`	Sets `fit` option for `resize`.
position / pos	Docs	`/s_200x200,pos_top/buffalo.png`	Sets `position` option for `resize`.
trim	Docs	`/trim_100/buffalo.png`
extend	Docs	`/extend_{top}_{right}_{bottom}_{left}/buffalo.png`	Extend / pad / extrude one or more edges of the image with either the provided background colour or pixels derived from the image.
background / b	_	`/r_45,b_00ff00/buffalo.png`
extract	Docs	`/extract_{left}_{top}_{width}_{height}/buffalo.png`	Extract/crop a region of the image.
crop	Docs	`/crop_{left}_{top}_{width}_{height}/buffalo.png`	Alias for extract. Extract/crop a region of the image.
format / f	Docs	`/format_webp/buffalo.png` or `/f_webp/buffalo.png`	Supported format: `jpg`, `jpeg`, `png`, `webp`, `avif`, `gif`, `heif`, `tiff` and `auto` (experimental only with middleware)
quality / q	_	`/quality_50/buffalo.png` or `/q_50/buffalo.png`	Accepted values: 0 to 100
rotate	Docs	`/rotate_45/buffalo.png`
enlarge	_	`/enlarge,s_2000x2000/buffalo.png`	Allow the image to be upscaled. By default the returned image will never be larger than the source in any dimension, while preserving the requested aspect ratio.
flip	Docs	`/flip/buffalo.png`
flop	Docs	`/flop/buffalo.png`
sharpen	Docs	`/sharpen_30/buffalo.png`
median	Docs	`/median_10/buffalo.png`
blur	Docs	`/blur_5/buffalo.png`
gamma	Docs	`/gamma_3/buffalo.png`
negate	Docs	`/negate/buffalo.png`
normalize	Docs	`/normalize/buffalo.png`
threshold	Docs	`/threshold_10/buffalo.png`
tint	Docs	`/tint_1098123/buffalo.png`
grayscale	Docs	`/grayscale/buffalo.png`
flatten	Docs	`/flatten/buffalo.png`	Remove alpha channel, if any, and replace with background colour.
modulate	Docs	`/modulate_brightness_saturation_hue/buffalo.png`	Transforms the image using brightness, saturation and hue rotation.
crop	Docs	`/crop_{left}_{top}_{width}_{height}/buffalo.png`	Alias for extract. Extract/crop a region of the image.
animated / a	-	`/animated/buffalo.gif` or `/a/buffalo.gif`	Experimental

License

MIT