sharp

sharp is a high-performance Node.js module for resizing, converting, and manipulating images, built on top of the libvips library. It’s typically used to convert large JPEG, PNG, WebP, AVIF, GIF, and TIFF images into smaller, web-friendly formats and dimensions, and is significantly faster than ImageMagick or GraphicsMagick for most operations because it processes images with minimal memory copying and per-operation streaming.

Beyond resizing, sharp exposes a chainable API for rotation, cropping, compositing, colour space conversion, and gamma correction, with colour spaces, embedded ICC profiles, and alpha transparency handled correctly. It ships prebuilt native bindings for common platforms so most projects can install and use it without a local build toolchain, and it works across Node.js, Deno, and Bun via Node-API.

What You Get

• A chainable Sharp() pipeline for resize, crop, rotate, composite, and format conversion operations
• Native bindings via libvips for JPEG, PNG, WebP, AVIF, GIF, TIFF, and SVG input/output
• Streaming and buffer-based I/O with Promise, callback, and Node.js stream.Duplex support
• Full TypeScript type definitions and detailed metadata/stats introspection (EXIF, ICC, dimensions)

Common Use Cases

• Resizing and compressing user-uploaded images for web delivery in an API or CMS backend
• Generating responsive image variants (thumbnails, srcset sizes) at build or request time
• Converting legacy formats (BMP, TIFF) to modern web formats like WebP and AVIF

Under The Hood

Architecture

sharp is a thin, chainable JavaScript layer over the libvips C image-processing library, connected through a native Node-API addon (src/sharp.cc, src/pipeline.cc, src/operations.cc). Calling sharp(input) returns a Sharp instance (lib/constructor.mjs) that extends stream.Duplex; each chained method (lib/resize.mjs, lib/composite.mjs, lib/operation.mjs, lib/colour.mjs, lib/channel.mjs, lib/output.mjs) mutates an internal options object rather than executing immediately, and the actual decode/transform/encode pipeline only runs when a terminal method (.toFile(), .toBuffer(), or piping the stream) triggers the native binding (lib/sharp.mjs), which selects a prebuilt sharp-<platform>-<version>.node binary matching the runtime’s OS/arch/libc via detect-libc. This lazy-pipeline-then-native-execute design lets libvips process images with minimal memory copying and per-operation streaming instead of decoding a full raster buffer per JS call.

Tech Stack

The public package is pure ESM/CJS dual-published JavaScript (dist/index.mjs and dist/index.cjs from a build step) with three runtime dependencies: @img/colour, detect-libc, and semver. The native layer is C++ against libvips (>=8.18.3, declared in package.json’s config.libvips) built via node-gyp/node-addon-api, with prebuilt binaries shipped as ~15 platform-specific optionalDependencies (@img/sharp-darwin-arm64, @img/sharp-linux-x64, etc., plus matching @img/sharp-libvips-* packages) so consumers avoid a local C++ toolchain. Node.js >=20.9.0 is required, and Deno/Bun are supported through Node-API v9 compatibility.

Code Quality

The repository has 59 files under test/unit covering individual operations (resize, composite, colour, output format, etc.) plus a separate test/types directory validating the 1,999-line lib/index.d.ts TypeScript definitions, and test/leak for memory-leak regression testing — a notably rigorous setup for a native-binding library. Error handling is centralized through a shared invalidParameterError factory in lib/is.mjs, used consistently (19 call sites) across the option-validation code in resize/operation/output rather than ad hoc throws. Naming is consistent and each public option is documented with JSDoc used to generate the published API docs site.

API Design

The chainable pipeline (sharp(input).resize().jpeg().toFile()) mirrors common Node stream/builder conventions and requires almost no boilerplate to get started — a single sharp(‘in.jpg’).resize(300).toFile(‘out.jpg’) covers the primary use case. Options are grouped logically per operation (resize, composite, output-format-specific encoders) and the library supports Promise, callback, and Duplex-stream usage side by side, so it fits equally into async/await code and pipe-based stream pipelines. The extensive TypeScript definitions and inline JSDoc give strong editor autocomplete and reduce the need to consult external docs for routine operations.