🖼️ IPX

<!-- automd:badges color=yellow -->

<!-- /automd -->

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

Used by Nuxt Image and Netlify and open to everyone!

Migration from v3 to v4

[!NOTE]
This is the active development branch for IPX v4. Check out v3 for v3 docs.

• The server creation APIs have changed. See the Programmatic API section for examples.
• The JSON error format has changed from { error: string } to { status, statusText, message }.

Using CLI

You can use ipx command to start server.

Using npx:

bashCopy
npx ipx serve --dir ./

Using bun

bashCopy
bunx 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.

Example: Using built-in server

<!-- automd:file code src="./examples/serve.ts" -->

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

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

// http://localhost:3000/w_512/picsum/1000
serveIPX(ipx);

<!-- /automd -->

Example: Using with h3

<!-- automd:file code src="./examples/h3.ts" -->

tsCopy
import { H3, serve } from "h3";

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

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

const app = new H3();

app.mount("/ipx", createIPXFetchHandler(ipx));

// http://localhost:3000/ipx/w_512/picsum/1000
serve(app);

<!-- /automd -->

Example: Using with express

<!-- automd:file code src="./examples/express.ts" -->

tsCopy
import Express from "express";

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

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

const app = Express();

app.use("/ipx", createIPXNodeHandler(ipx));

// http://localhost:3000/ipx/w_512/picsum/1000
app.listen(3000, () => {
  console.log("Server is running on http://localhost:3000");
});

<!-- /automd -->

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