ipx-nightly
v3.0.0-1705019392.624b9db
Published
High performance, secure and easy-to-use image optimizer.
Downloads
5
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:
{}
- 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 |