https://github.com/platformatic/image-optimizer
Detect, fetch, and optimize images with sharp, with optional queue-backed processing via @platformatic/job-queue.
https://github.com/platformatic/image-optimizer
Last synced: 25 days ago
JSON representation
Detect, fetch, and optimize images with sharp, with optional queue-backed processing via @platformatic/job-queue.
- Host: GitHub
- URL: https://github.com/platformatic/image-optimizer
- Owner: platformatic
- License: apache-2.0
- Created: 2026-02-19T05:57:48.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-02-21T05:33:15.000Z (29 days ago)
- Last Synced: 2026-02-21T12:31:39.115Z (29 days ago)
- Language: TypeScript
- Size: 258 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Notice: NOTICE
- Dco: dco.txt
Awesome Lists containing this project
README
# @platformatic/image-optimizer
Detect, fetch, and optimize images with [`sharp`](https://sharp.pixelplumbing.com/), with optional queue-backed processing via [`@platformatic/job-queue`](https://github.com/platformatic/job-queue).
## Features
- Detects image type from file signatures (magic bytes)
- Optimizes raster images (`jpeg`, `png`, `webp`, `avif`)
- Prevents animated image optimization
- Supports optional SVG passthrough
- Provides `fetchAndOptimize()` for URL-based workflows (via `undici.request()`)
- Provides queue APIs (`Queue`, `createQueue`) powered by [`@platformatic/job-queue`](https://www.npmjs.com/package/@platformatic/job-queue) for distributed work
- Throws structured `ImageError` objects
## Installation
```bash
npm i @platformatic/image-optimizer
```
## API
### `optimize(buffer, width, quality, allowSVG = false)`
Optimizes an input image buffer.
- `width`: target max width (`withoutEnlargement` is enabled)
- `quality`: output quality used by format-specific encoders
- `allowSVG`: when `false` (default), SVG images are not optimized and it throws an error
### `fetchAndOptimize(url, width, quality, allowSVG = false)`
Fetches an image and then runs `optimize()`.
Returns:
- `buffer`: optimized image buffer
- `contentType`: upstream `content-type` response header (or `null`)
- `cacheControl`: upstream `cache-control` response header (or `null`)
### `detectImageType(buffer)`
Returns the detected image type (for example `jpeg`, `png`, `webp`) or `null`.
### `Queue`
Queue-backed optimizer powered by [`@platformatic/job-queue`](https://www.npmjs.com/package/@platformatic/job-queue).
Methods:
- `start()`
- `stop()`
- `fetchAndOptimize(url, width, quality, allowSVG?, enqueueOptions?)` (auto-starts on first use)
Notes:
- Queue processing is URL-based (`fetchAndOptimize`) and returns `{ buffer, contentType, cacheControl }`.
- `enqueueOptions` is forwarded to `@platformatic/job-queue` `enqueueAndWait()` (for example: `timeout`, `maxAttempts`, `resultTTL`).
### `createQueue(options?)`
Creates and starts a `Queue` instance.
## Example
```ts
import { createQueue } from '@platformatic/image-optimizer'
const queue = await createQueue({ concurrency: 2 })
const { buffer, contentType, cacheControl } = await queue.fetchAndOptimize('https://example.com/image.jpg', 800, 75)
await queue.stop()
```
## License
Apache-2.0 - See [LICENSE](LICENSE) for more information.