@cyb3rcore/sharpify

Fastify plugin for on-the-fly image transformation with sharp. Tightly integrated with @fastify/static — serves originals via static, transforms on request, caches derivatives to disk.

fastify.register(fastifyStatic, { root: 'public', prefix: '/', wildcard: true })
fastify.register(sharpify, {
  prefix: '/images/',
  sourceDir: 'public/images',
  cacheDir: 'public/_cache',
})

Install

npm install @cyb3rcore/sharpify

Requires @fastify/static and fastify as peer dependencies.

How it works

GET /images/photo.jpg?w=400&fmt=webp&q=80
  ↓
sharpify route handler (GET /images/*)
  ↓
Has transform params?  →  no  →  reply.sendFile()  →  @fastify/static serves original
  ↓ yes
Compute cache key (SHA-256 of source path + mtime + params)
  ↓
Cache file exists?  →  yes  →  reply.sendFile(cacheFile)  →  @fastify/static streams it
  ↓ no
Sharp pipeline: read source → resize → convert → write to cache (atomic .tmp + rename)
  ↓
reply.sendFile(cacheFile)  →  @fastify/static serves the cached derivative

Requests without any transform params pass through to @fastify/static zero-overhead — sharpify doesn't touch them.

Registration

import Fastify from 'fastify'
import fastifyStatic from '@fastify/static'
import sharpify from '@cyb3rcore/sharpify'

const app = Fastify()

// Register @fastify/static first — sharpify delegates to it via reply.sendFile()
await app.register(fastifyStatic, {
  root: 'public',
  prefix: '/',
  wildcard: true,
})

// Register sharpify — it owns /images/ route for transformed images
await app.register(sharpify, {
  prefix: '/images/',
  sourceDir: 'public/images',
  cacheDir: 'public/_cache',
})

await app.listen({ port: 3000 })

Query parameters

Core operations

| Operation | Param | Type | Default | Notes | | --------------- | ------ | ------------- | -------------- | ------------------------------------ | | Width | w | number | source | Clamped to maxWidth (default 4096) | | Height | h | number | source | Clamped to maxHeight (default 4096)| | Fit | fit | string | cover | cover, contain, fill, inside, outside | | Position | pos | string | centre | Also entropy, attention strategies | | Format | fmt | string | auto (Accept) | jpeg, png, webp, avif, tiff, gif | | Quality | q | number(1-100) | 80 | Mapped per-format | | Without enlarge | we | boolean | true | Don't upscale |

Image adjustments

| Operation | Param | Type | Description | | ---------------------- | ------------- | -------------- | ----------------------------------------- | | Sharpen | sharp | number(sigma) | Post-resize sharpen | | Sharpen (fine) | sharpm | number(m1) | Fine control with sharp | | Blur | blur | number(sigma) | Gaussian blur (capped at 100) | | Rotate | rot | number(deg) | Arbitrary rotation | | Auto-orient | or | boolean | Respect EXIF orientation | | Trim | trim | boolean | Auto-trim similar-colored borders | | Trim threshold | trimt | number | Sensitivity for trim | | Greyscale | bw | boolean | Convert to black & white | | Flip (vertical) | flip | boolean | Mirror vertically | | Flop (horizontal) | flop | boolean | Mirror horizontally | | Brightness | bri | number | Multiplier via modulate | | Saturation | sat | number | Multiplier via modulate | | Hue rotate | hue | number(deg) | Hue rotation via modulate | | Normalise contrast | con | boolean | Histogram stretch | | Negate | neg | boolean | Invert colours | | Gamma | gam | number | Gamma correction | | Tint | tint | hex colour | ff4400 — tint the image | | Background | bg | hex colour | Flatten alpha onto this colour | | Threshold | thresh | number(0-255) | Posterize at threshold | | Median filter | median | number(3-9) | Noise reduction | | Linear (mult) | mult | number | output = mult * input + offset | | Linear (offset) | offset | number | | | Region crop | crop | string | left,top,width,height | | Pad border | pad | number/string | N (all) or t,r,b,l | | Preserve metadata | meta | boolean | Keep EXIF/ICC profiles | | Remove alpha | strip-alpha | boolean | Strip transparency channel | | Lossless | lossless | boolean | For WebP, AVIF |

Format-specific controls

| Param | Affects | Default | Notes | | -------------- | -------------- | ------------ | --------------------------------- | | progressive | JPEG | false | Progressive (interlace) scan | | mozjpeg | JPEG | false | mozjpeg defaults | | chroma | JPEG, AVIF | 4:4:4 | Chroma subsampling | | effort | WebP, AVIF, PNG | varies | Encoding speed/quality tradeoff | | bitdepth | AVIF, PNG | 8 | Bit depth | | palette | PNG | false | Indexed PNG (quantized) | | compression | PNG | 6 | zlib compression level | | preset | WebP | default | Encoding preset |

Security

| Param | Type | Default | Description | | ---------- | ------ | --------- | ----------------------------------- | | timeout | number | 30 | Processing timeout in seconds |

Content negotiation

When fmt is not specified, sharpify negotiates the best format from the Accept header:

1. AVIF (image/avif) — best compression, when browser supports it
2. WebP (image/webp) — widely supported modern format
3. JPEG / PNG — fallback based on source format

Formats that don't support alpha (JPEG) are skipped when the source image has an alpha channel.

Plugin options

interface SharpifyOptions {
  // Required
  prefix: string          // URL prefix, e.g. '/images/'
  sourceDir: string       // Absolute path to source images
  cacheDir: string        // Absolute path to cache directory

  // Security / limits
  maxWidth?: number       // default 4096
  maxHeight?: number      // default 4096
  timeoutSeconds?: number // default 30
  maxConcurrency?: number // default 4
  withoutEnlargement?: boolean // default true
  maxCacheSize?: number   // default 1GB (LRU eviction)
}

Caching

Sharpify caches every transformed image to disk. The cache key is a SHA-256 hash of:

sourceRelativePath + sourceMtime + canonicalParams

• Editing the source file changes the mtime → new cache key → old file orphaned → eventually evicted by LRU
• Two-char subdirectory layout prevents inode pressure from many cache files
• Atomic writes (.tmp.PID → renameSync) prevent serving partial files
• LRU eviction removes least-recently-accessed files when total cache exceeds maxCacheSize
• @fastify/static multi-root (['_cache', 'public']) — sharpify writes to cache, static serves from cache; on cache hit there's zero sharp involvement

DoS protections

| Vector | Mitigation | | ------------------- | -------------------------------------------------------- | | Memory bomb | Output dimensions capped at 4096, withoutEnlargement: true, limitInputPixels | | CPU exhaustion | sharp().timeout({ seconds: 30 }) on every pipeline | | Slow operations | Blur capped at sigma 100, median capped at 5 | | Thread pool | Concurrency semaphore (default 4 max) | | Disk fill | LRU eviction, quantized cache keys | | Path traversal | Hash-based cache filenames, prefix guard on sourceDir | | Image bomb | failOn: 'error', unlimited: false |

Error handling

| Scenario | Behavior | | ---------------------------- | ----------------------------------------------------- | | Sharp timeout | Logs warning, serves original image | | Image not found | 404 from reply.sendFile() | | Invalid query params | Silently clamp to defaults | | Sharp processing error | Logs error, serves original | | Sharp not installed | Friendly error at plugin registration |

Tests

 npm test        # 64 tests across 5 files
npm run build   # TypeScript compilation

License

MIT