Sharp Image Processing in the Strapi Upload Plugin#

Overview#

Sharp is the core image processing engine used by Strapi's upload plugin. All image manipulation — metadata extraction, resizing, optimization, thumbnail generation, and animation handling — runs through Sharp (backed by libvips). The primary implementation lives in image-manipulation.ts.

Key Source Files#

Format Support#

Three format tiers control which operations apply 1:

Note: SVG and AVIF are not resizable. GIF is resizable but not optimizable (no quality pass). The isSupportedImage method was removed in Strapi 5; use isImage or isOptimizableImage instead 2.

Core Operations#

Metadata & Dimensions#

getMetadata() supports both file-path and stream inputs. For path-based files it calls sharp(file.filepath).metadata(); for streams it pipes through a sharp() pipeline. getDimensions() wraps this to return { width, height }.

Optimization#

optimize() runs when either sizeOptimization or autoOrientation is enabled in Media Library settings:

• Quality reduction: Re-encodes the image at quality: 80 (when sizeOptimization is on) or quality: 100 3.
• Auto-rotation: Calls transformer.rotate() to apply EXIF orientation 4.
• Safety check: If the optimized output is larger than the original, the original file is returned unchanged 5.
• Both stream and filepath paths are supported; { animated: true } is passed to Sharp to preserve animation frames 6 7.

Thumbnail Generation#

generateThumbnail() only runs if the image exceeds the threshold. The fixed thumbnail size is 245 × 156 px, fit: 'inside' 8. If the image is smaller than these dimensions, no thumbnail is created.

Responsive Breakpoints#

generateResponsiveFormats() generates one resized variant per configured breakpoint, but only for dimensions smaller than the original. Default breakpoints 9:

Breakpoints can be overridden in /config/plugins via the breakpoints key. Custom sizes (e.g., xlarge: 1920, xsmall: 64) are supported 10. Breakpoint changes only apply to new uploads.

Each breakpoint is processed with resizeFileTo(), which calls sharp({ animated: true }).resize(options) to preserve all frames in animated GIFs and WebPs. The pageHeight field (single-frame height) is used for dimension reporting of animated images 11 7.

Faulty Image Detection#

isFaultyImage() calls sharp.stats() on the file to detect corrupted or malformed images before further processing.

Memory Management & Configuration#

Uploading large or high-megapixel images previously caused OOM crashes on memory-constrained environments (e.g., Strapi Cloud free tier with 512 MB RAM). The root cause: Sharp/libvips would decode the full source image for every responsive breakpoint concurrently, while also retaining cached pixel data between operations 12.

Defaults set at plugin registration 13:

• sharp.cache(false) — disables libvips' decoded-image cache.
• sharp.concurrency(1) — limits the libvips thread pool to 1.
• Responsive breakpoints are generated sequentially (not via Promise.all) to cap peak memory usage.

These defaults are configurable via config/plugins.ts:

upload: {
  config: {
    sharp: {
      cache: true, // re-enable if you have RAM headroom
      concurrency: 2, // increase for multi-core, high-memory deployments
    },
  },
}

The Config type 14 and default values 15 document this shape. The concurrentUploadSize config key (default 1) provides an additional parallel upload limit 16.

Related Memory Issues#

A separate memory-growth issue (issue #25199) was tracked and resolved by two fixes: 17

1. PR #26046 — Sharp cache/concurrency defaults (described above).
2. PR #26678 (≥ 5.48.1) — MIME detection was reading entire files into memory and retaining a subarray view; now uses a flat 4100-byte read.

Both fixes are present in current develop. If memory still grows, take a heap snapshot with --inspect to distinguish V8-heap vs. native (libvips) retention.

Animated Image Support#

Prior to the fix in PR #26126, animated GIFs and WebPs lost all frames after upload because sharp() was called without { animated: true }. The fix:

• Passes { animated: true } to all sharp() constructor calls in resizeFileTo() and optimize().
• Uses pageHeight (height of a single frame) instead of height (stacked height of all frames) for dimension metadata.
• A declare module 'sharp' augmentation adds pageHeight to OutputInfo types as a workaround until Sharp ≥ 0.34.2 18.

Large Upload Handling#

For uploads exceeding defaults, two layers must be configured 10:

1. Body middleware (config/middlewares): increase formidable.maxFileSize and formLimit.
2. Plugin config (config/plugins): set sizeLimit (in bytes; default 1 GB per config.ts 19).
3. Request timeout: strapi.server.httpServer.requestTimeout defaults to 330 seconds; increase in config/server or via bootstrap().

Upstream proxies (nginx client_max_body_size, load balancers) also need adjustment for large files.