ipx

What is ipx?

The ipx npm package is an image processing server that allows you to manipulate images on-the-fly. It supports various image transformations such as resizing, cropping, and format conversion, making it useful for web applications that need dynamic image processing.

What are ipx's main functionalities?

Resizing Images

This feature allows you to resize images to specified dimensions. In the code sample, the image is resized to a width of 300 pixels and a height of 200 pixels.

const ipx = require('ipx')();
const url = '/_ipx/w_300,h_200/image.jpg';
const result = await ipx(url);

Cropping Images

This feature allows you to crop images to specified dimensions. In the code sample, the image is cropped to a width of 300 pixels and a height of 200 pixels.

const ipx = require('ipx')();
const url = '/_ipx/c_crop,w_300,h_200/image.jpg';
const result = await ipx(url);

Format Conversion

This feature allows you to convert images to different formats. In the code sample, the image is converted to the WebP format.

const ipx = require('ipx')();
const url = '/_ipx/f_webp/image.jpg';
const result = await ipx(url);

Other packages similar to ipx

sharp

Sharp is a high-performance image processing library that supports resizing, cropping, and format conversion. It is known for its speed and efficiency, making it a popular choice for server-side image processing. Compared to ipx, sharp is more of a low-level library that requires more manual setup and configuration.

jimp

Jimp is a JavaScript image processing library that supports various image manipulations such as resizing, cropping, and format conversion. It is easy to use and does not require any external dependencies. Compared to ipx, Jimp is more suitable for client-side applications and smaller projects.

gm

GraphicsMagick (gm) is a Node.js wrapper for the GraphicsMagick and ImageMagick image processing libraries. It supports a wide range of image manipulations and is highly configurable. Compared to ipx, gm offers more advanced features but requires the installation of external software.

README

🖼️ IPX

[!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