{"id":13457642,"url":"https://github.com/unjs/ipx","last_synced_at":"2026-04-01T23:58:55.771Z","repository":{"id":37235184,"uuid":"113739873","full_name":"unjs/ipx","owner":"unjs","description":"🖼️ High performance, secure and easy-to-use image optimizer.","archived":false,"fork":false,"pushed_at":"2025-03-21T10:56:59.000Z","size":2654,"stargazers_count":2170,"open_issues_count":42,"forks_count":71,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-10T21:34:47.706Z","etag":null,"topics":["cdn","docker","image","libvips","optimize","proxy","resize","sharp","webp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-12-10T10:04:59.000Z","updated_at":"2025-05-09T09:37:16.000Z","dependencies_parsed_at":"2023-10-02T11:04:06.685Z","dependency_job_id":"950c69e8-db0e-43a0-ad0e-4bb94024330c","html_url":"https://github.com/unjs/ipx","commit_stats":{"total_commits":377,"total_committers":29,"mean_commits":13.0,"dds":0.6631299734748011,"last_synced_commit":"c40e1c2eafda5c1077b1ee97874409773b990157"},"previous_names":["nuxt-contrib/ipx"],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Fipx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Fipx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Fipx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Fipx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unjs","download_url":"https://codeload.github.com/unjs/ipx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745450,"owners_count":21957374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdn","docker","image","libvips","optimize","proxy","resize","sharp","webp"],"created_at":"2024-07-31T09:00:32.746Z","updated_at":"2026-04-01T23:58:55.756Z","avatar_url":"https://github.com/unjs.png","language":"TypeScript","readme":"# 🖼️ IPX\n\n\u003c!-- automd:badges color=yellow --\u003e\n\n[![npm version](https://img.shields.io/npm/v/ipx?color=yellow)](https://npmjs.com/package/ipx)\n[![npm downloads](https://img.shields.io/npm/dm/ipx?color=yellow)](https://npm.chart.dev/ipx)\n\n\u003c!-- /automd --\u003e\n\nHigh performance, secure and easy-to-use image optimizer powered by [sharp](https://github.com/lovell/sharp) and [svgo](https://github.com/svg/svgo).\n\nUsed by [Nuxt Image](https://image.nuxt.com/) and [Netlify](https://www.npmjs.com/package/@netlify/ipx) and open to everyone!\n\n## Migration from v3 to v4\n\n\u003e [!NOTE]\n\u003e This is the active development branch for IPX v4. Check out [v3](https://github.com/unjs/ipx/tree/v3) for v3 docs.\n\n- The server creation APIs have changed. See the Programmatic API section for examples.\n- The JSON error format has changed from `{ error: string }` to `{ status, statusText, message }`.\n\n## Using CLI\n\nYou can use `ipx` command to start server.\n\nUsing `npx`:\n\n```bash\nnpx ipx serve --dir ./\n```\n\nUsing `bun`\n\n```bash\nbunx ipx serve --dir ./\n```\n\nThe default serve directory is the current working directory.\n\n## Programmatic API\n\nYou can use IPX as a middleware or directly use IPX interface.\n\n**Example:** Using built-in server\n\n\u003c!-- automd:file code src=\"./examples/serve.ts\" --\u003e\n\n```ts [serve.ts]\nimport { serveIPX, createIPX, ipxFSStorage, ipxHttpStorage } from \"ipx\";\n\nconst ipx = createIPX({\n  storage: ipxFSStorage({ dir: \"./public\" }),\n  httpStorage: ipxHttpStorage({ domains: [\"picsum.photos\"] }),\n  alias: { \"/picsum\": \"https://picsum.photos\" },\n});\n\n// http://localhost:3000/w_512/picsum/1000\nserveIPX(ipx);\n```\n\n\u003c!-- /automd --\u003e\n\n**Example**: Using with [h3](https://h3.dev)\n\n\u003c!-- automd:file code src=\"./examples/h3.ts\" --\u003e\n\n```ts [h3.ts]\nimport { H3, serve } from \"h3\";\n\nimport {\n  createIPX,\n  ipxFSStorage,\n  ipxHttpStorage,\n  createIPXFetchHandler,\n} from \"ipx\";\n\nconst ipx = createIPX({\n  storage: ipxFSStorage({ dir: \"./public\" }),\n  httpStorage: ipxHttpStorage({ domains: [\"picsum.photos\"] }),\n  alias: { \"/picsum\": \"https://picsum.photos\" },\n});\n\nconst app = new H3();\n\napp.mount(\"/ipx\", createIPXFetchHandler(ipx));\n\n// http://localhost:3000/ipx/w_512/picsum/1000\nserve(app);\n```\n\n\u003c!-- /automd --\u003e\n\n**Example:** Using with [express](https://expressjs.com)\n\n\u003c!-- automd:file code src=\"./examples/express.ts\" --\u003e\n\n```ts [express.ts]\nimport Express from \"express\";\n\nimport {\n  createIPX,\n  ipxFSStorage,\n  ipxHttpStorage,\n  createIPXNodeHandler,\n} from \"ipx\";\n\nconst ipx = createIPX({\n  storage: ipxFSStorage({ dir: \"./public\" }),\n  httpStorage: ipxHttpStorage({ domains: [\"picsum.photos\"] }),\n  alias: { \"/picsum\": \"https://picsum.photos\" },\n});\n\nconst app = Express();\n\napp.use(\"/ipx\", createIPXNodeHandler(ipx));\n\n// http://localhost:3000/ipx/w_512/picsum/1000\napp.listen(3000, () =\u003e {\n  console.log(\"Server is running on http://localhost:3000\");\n});\n```\n\n\u003c!-- /automd --\u003e\n\n## URL Examples\n\nGet original image:\n\n`/_/static/buffalo.png`\n\nChange format to `webp` and keep other things same as source:\n\n`/f_webp/static/buffalo.png`\n\nAutomatically convert to a preferred format (avif/webp/jpeg). Uses the browsers `accept` header to negotiate:\n\n`/f_auto/static/buffalo.png`\n\nKeep original format (`png`) and set width to `200`:\n\n`/w_200/static/buffalo.png`\n\nResize to `200x200px` using `embed` method and change format to `webp`:\n\n`/embed,f_webp,s_200x200/static/buffalo.png`\n\n## Config\n\nYou can universally customize IPX configuration using `IPX_*` environment variables.\n\n- `IPX_ALIAS`\n  - Default: `{}`\n\n### Filesystem Source Options\n\n(enabled by default with CLI only)\n\n#### `IPX_FS_DIR`\n\n- Default: `.` (current working directory)\n\n#### `IPX_FS_MAX_AGE`\n\n- Default: `300`\n\n### HTTP(s) Source Options\n\n(enabled by default with CLI only)\n\n#### `IPX_HTTP_DOMAINS`\n\n- Default: `[]`\n\n#### `IPX_HTTP_MAX_AGE`\n\n- Default: `300`\n\n#### `IPX_HTTP_FETCH_OPTIONS`\n\n- Default: `{}`\n\n#### `IPX_HTTP_ALLOW_ALL_DOMAINS`\n\n- Default: `false`\n\n## Modifiers\n\n| Property       | Docs                                                            | Example                                              | Comments                                                                                                                                                          |\n| -------------- | :-------------------------------------------------------------- | :--------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| width / w      | [Docs](https://sharp.pixelplumbing.com/api-resize#resize)       | `/width_200/buffalo.png` or `/w_200/buffalo.png`     |\n| height / h     | [Docs](https://sharp.pixelplumbing.com/api-resize#resize)       | `/height_200/buffalo.png` or `/h_200/buffalo.png`    |\n| resize / s     | [Docs](https://sharp.pixelplumbing.com/api-resize#resize)       | `/s_200x200/buffalo.png`                             |\n| kernel         | [Docs](https://sharp.pixelplumbing.com/api-resize#resize)       | `/s_200x200,kernel_nearest/buffalo.png`              | Supported kernel: `nearest`, `cubic`, `mitchell`, `lanczos2` and `lanczos3` (default).                                                                            |\n| fit            | [Docs](https://sharp.pixelplumbing.com/api-resize#resize)       | `/s_200x200,fit_outside/buffalo.png`                 | Sets `fit` option for `resize`.                                                                                                                                   |\n| position / pos | [Docs](https://sharp.pixelplumbing.com/api-resize#resize)       | `/s_200x200,pos_top/buffalo.png`                     | Sets `position` option for `resize`.                                                                                                                              |\n| trim           | [Docs](https://sharp.pixelplumbing.com/api-resize#trim)         | `/trim_100/buffalo.png`                              |\n| extend         | [Docs](https://sharp.pixelplumbing.com/api-resize#extend)       | `/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.                                |\n| background / b | \\_                                                              | `/r_45,b_00ff00/buffalo.png`                         |\n| extract        | [Docs](https://sharp.pixelplumbing.com/api-resize#extract)      | `/extract_{left}_{top}_{width}_{height}/buffalo.png` | Extract/crop a region of the image.                                                                                                                               |\n| crop           | [Docs](https://sharp.pixelplumbing.com/api-resize#extract)      | `/crop_{left}_{top}_{width}_{height}/buffalo.png`    | Alias for extract. Extract/crop a region of the image.                                                                                                            |\n| format / f     | [Docs](https://sharp.pixelplumbing.com/api-output#toformat)     | `/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)                                      |\n| quality / q    | \\_                                                              | `/quality_50/buffalo.png` or `/q_50/buffalo.png`     | Accepted values: 0 to 100                                                                                                                                         |\n| rotate         | [Docs](https://sharp.pixelplumbing.com/api-operation#rotate)    | `/rotate_45/buffalo.png`                             |\n| 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. |\n| flip           | [Docs](https://sharp.pixelplumbing.com/api-operation#flip)      | `/flip/buffalo.png`                                  |\n| flop           | [Docs](https://sharp.pixelplumbing.com/api-operation#flop)      | `/flop/buffalo.png`                                  |\n| sharpen        | [Docs](https://sharp.pixelplumbing.com/api-operation#sharpen)   | `/sharpen_30/buffalo.png`                            |\n| median         | [Docs](https://sharp.pixelplumbing.com/api-operation#median)    | `/median_10/buffalo.png`                             |\n| blur           | [Docs](https://sharp.pixelplumbing.com/api-operation#blur)      | `/blur_5/buffalo.png`                                |\n| gamma          | [Docs](https://sharp.pixelplumbing.com/api-operation#gamma)     | `/gamma_3/buffalo.png`                               |\n| negate         | [Docs](https://sharp.pixelplumbing.com/api-operation#negate)    | `/negate/buffalo.png`                                |\n| normalize      | [Docs](https://sharp.pixelplumbing.com/api-operation#normalize) | `/normalize/buffalo.png`                             |\n| threshold      | [Docs](https://sharp.pixelplumbing.com/api-operation#threshold) | `/threshold_10/buffalo.png`                          |\n| tint           | [Docs](https://sharp.pixelplumbing.com/api-colour#tint)         | `/tint_1098123/buffalo.png`                          |\n| grayscale      | [Docs](https://sharp.pixelplumbing.com/api-colour#grayscale)    | `/grayscale/buffalo.png`                             |\n| flatten        | [Docs](https://sharp.pixelplumbing.com/api-operation#flatten)   | `/flatten/buffalo.png`                               | Remove alpha channel, if any, and replace with background colour.                                                                                                 |\n| modulate       | [Docs](https://sharp.pixelplumbing.com/api-operation#modulate)  | `/modulate_brightness_saturation_hue/buffalo.png`    | Transforms the image using brightness, saturation and hue rotation.                                                                                               |\n| crop           | [Docs](https://sharp.pixelplumbing.com/api-resize#extract)      | `/crop_{left}_{top}_{width}_{height}/buffalo.png`    | Alias for extract. Extract/crop a region of the image.                                                                                                            |\n| animated / a   | -                                                               | `/animated/buffalo.gif` or `/a/buffalo.gif`          | Experimental                                                                                                                                                      |\n\n## License\n\n[MIT](./LICENSE)\n","funding_links":[],"categories":["TypeScript","Packages"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funjs%2Fipx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funjs%2Fipx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funjs%2Fipx/lists"}