Skip to content
/ ipx Public

🖼️ High performance, secure and easy-to-use image optimizer.

License

Notifications You must be signed in to change notification settings

unjs/ipx

Repository files navigation

🖼️ IPX

npm version npm downloads

Note

This is the active branch for IPX v2. Check out ipx/v1 for v1 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 ./

Usin bun

bun x npx ipx serve --dir ./

The default serve directory is the current working directory.

Programatic 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

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
height / h Docs /height_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.
format / f Docs /format_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 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
animated - /animated/buffalo.gif Experimental

License

MIT