sharp ships prebuilt native binaries for most platforms (macOS x64/arm64, Linux x64/arm64, Windows x64). No manual build step is required in most cases. If you are on an unsupported platform or using a custom Node.js ABI, run:

npm install --build-from-source sharp

Ensure Node.js ^18.17.0 or >= 20.3.0 is used. The package requires Node-API v9.

Project setup

1. Copy the source/ directory into your project, for example at lib/sharp/.
2. Install runtime dependencies (see above).
3. Import directly from lib/sharp/index.js or point your module alias at it:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "sharp": ["./lib/sharp/index.d.ts"]
    }
  }
}

4. In CommonJS projects:

const sharp = require('./lib/sharp/index.js');

5. In ESM/TypeScript projects:

import sharp from './lib/sharp/index.js';
// or, if using the published package directly:
import sharp from 'sharp';

6. No environment variables are required by default. To control threading, call sharp.concurrency(n) at startup.

Public API

sharp (constructor)

declare function sharp(
  input?: string | Buffer | ArrayBuffer | Uint8Array | Array<...>,
  options?: sharp.SharpOptions
): sharp.Sharp;

Creates a processing pipeline. Pass a file path string, a Buffer, or nothing (for stream input). The returned Sharp instance is a Duplex stream and supports method chaining. Use options.animated: true for multi-frame GIF/WebP processing.

sharp.Sharp (instance methods)

interface Sharp extends Duplex {
  resize(width?: number, height?: number, options?: ResizeOptions): Sharp;
  rotate(angle?: number, options?: RotateOptions): Sharp;
  composite(images: OverlayOptions[]): Sharp;
  toFile(fileOut: string, callback?: (err: Error, info: OutputInfo) => void): Promise<OutputInfo>;
  toBuffer(options?: ToBufferOptions): Promise<Buffer>;
  jpeg(options?: JpegOptions): Sharp;
  png(options?: PngOptions): Sharp;
  webp(options?: WebpOptions): Sharp;
  avif(options?: AvifOptions): Sharp;
  gif(options?: GifOptions): Sharp;
  tiff(options?: TiffOptions): Sharp;
  raw(options?: RawOptions): Sharp;
  metadata(): Promise<Metadata>;
  stats(): Promise<Stats>;
}

The central chainable instance. Each transformation method returns this, so calls can be composed in any order. Terminal methods (toFile, toBuffer) return Promises when no callback is supplied.

sharp.format

const format: FormatEnum;

A static object describing which input/output formats are available in the current libvips build. Check sharp.format.avif.output.buffer before encoding to AVIF to guard against builds without OpenJPEG or AOM support.

sharp.versions

const versions: {
  sharp: string;
  vips: string;
  aom?: string;
  heif?: string;
  jpeg?: string;
  png?: string;
  webp?: string;
  // ... more
};

Static object exposing the exact versions of sharp and all bundled native libraries. Useful for diagnostics and conditional feature detection at runtime.

Working examples

Scenario - Resize and convert to WebP

Accepts an uploaded buffer, resizes it to a maximum 800px width while preserving aspect ratio, and writes a WebP file optimised for web delivery.

import sharp from './lib/sharp/index.js';

async function processUpload(inputBuffer: Buffer, outputPath: string): Promise<void> {
  const info = await sharp(inputBuffer)
    .resize({ width: 800, withoutEnlargement: true })
    .webp({ quality: 80 })
    .toFile(outputPath);

  console.log(`Written ${info.format} ${info.width}x${info.height} (${info.size} bytes)`);
}

Scenario - Composite watermark over image

Loads a base JPEG and overlays a semi-transparent PNG watermark at the bottom-right corner, then returns the result as a buffer for streaming to S3 or a CDN.

import sharp from './lib/sharp/index.js';
import { readFileSync } from 'node:fs';

async function addWatermark(
  baseImagePath: string,
  watermarkPath: string
): Promise<Buffer> {
  const { width = 800, height = 600 } = await sharp(baseImagePath).metadata();

  return sharp(baseImagePath)
    .composite([
      {
        input: watermarkPath,
        gravity: 'southeast',
        blend: 'over',
      },
    ])
    .jpeg({ quality: 90, mozjpeg: true })
    .toBuffer();
}

Scenario - Generate thumbnail strip from animated GIF

Extracts the first frame of an animated GIF, resizes it to a 150x150 cover thumbnail, and saves as PNG. Uses pages: 1 to avoid processing all frames.

import sharp from './lib/sharp/index.js';

async function gifThumbnail(inputPath: string, outputPath: string): Promise<void> {
  await sharp(inputPath, { pages: 1 })
    .resize(150, 150, { fit: 'cover', position: 'entropy' })
    .png({ compressionLevel: 9 })
    .toFile(outputPath);
}

Scenario - Pipe through a Node.js stream

Attach sharp as a transform stream between a read stream and a write stream for memory-efficient large file processing.

import sharp from './lib/sharp/index.js';
import { createReadStream, createWriteStream } from 'node:fs';

function streamResize(inputFile: string, outputFile: string): void {
  const transformer = sharp()
    .resize(1280, 720, { fit: 'inside' })
    .avif({ quality: 60 });

  createReadStream(inputFile)
    .pipe(transformer)
    .pipe(createWriteStream(outputFile));
}

File walkthrough

• index.js - Requires constructor.js then mutates the class prototype by passing it through each feature module; this is the only file you should import.
• index.d.ts - Canonical TypeScript declarations; contains all interfaces (SharpOptions, ResizeOptions, OutputInfo, etc.) and the sharp function overloads.
• constructor.js - Instantiates the Sharp Duplex stream, initialises this.options, and stores pipeline state.
• input.js - Parses and validates input descriptors (file path, buffer, stream, create, text, raw); attaches metadata() and stats().
• resize.js - Implements resize(), extend(), extract(), and trim() with full option validation.
• composite.js - Implements composite(), accepting an array of overlay descriptors with blend mode, gravity, and offset options.
• operation.js - Geometric and tonal operations: rotate(), autoOrient(), flip(), flop(), sharpen(), median(), blur(), flatten(), unflatten(), gamma(), negate(), normalise(), clahe(), convolve(), threshold(), boolean(), linear(), recomb(), modulate().
• colour.js - tint(), greyscale() / grayscale(), pipelineColourspace(), toColourspace() / toColorspace().
• channel.js - Alpha and channel operations: removeAlpha(), ensureAlpha(), extractChannel(), joinChannel(), bandBoolOp().
• output.js - All output format encoders and terminal methods; maps file extensions to libvips format names.
• utility.js - Static methods on the constructor: cache(), concurrency(), counters(), simd(), queue.
• is.js - Internal predicates (defined, integer, inRange, etc.); not exported publicly.
• libvips.js - Loads the prebuilt native .node binding and validates the libvips version at require time.
• sharp.js - Thin wrapper that exposes the raw Node-API binding object consumed by the JS layer.

Common pitfalls and fixes

• Prebuilt binary mismatch after npm ci on a different OS/arch: Run npm rebuild sharp or delete node_modules/sharp and reinstall on the target platform.
• Error: Input file is missing on relative paths: sharp resolves paths relative to process.cwd(), not __dirname; use path.resolve(__dirname, 'file.jpg').
• Animated GIF/WebP frames not processed: Pass { animated: true } in SharpOptions; default reads only the first frame.
• JP2 output throws JP2 output requires libvips with support for OpenJPEG: The prebuilt binary for your platform omits OpenJPEG; build from source with npm install --build-from-source sharp.
• Memory growth under high concurrency: sharp buffers are backed by libvips memory; call sharp.cache(false) in long-running services if RSS grows unbounded, and tune sharp.concurrency(n) to match available CPU cores.
• ESM import sharp from 'sharp' fails with ERR_REQUIRE_ESM or default export undefined: sharp is CJS; use import sharp from 'sharp' with "esModuleInterop": true in tsconfig, or use createRequire in pure ESM contexts.

Vibe-coding prompt template

I have the sharp image processing library source copied into `lib/sharp/` in my project.
I also have `USAGE.md` in the same directory describing its API and integration steps.
The upstream npm package is `user@example.com`.

Please help me integrate sharp into my project step by step:

1. Read `USAGE.md` and `lib/sharp/index.d.ts` to understand the available API.
2. Install all required runtime dependencies listed in `USAGE.md`.
3. Create a TypeScript module at `src/images/processor.ts` that exports:
   - `resizeImage(input: Buffer, width: number, height: number): Promise<Buffer>`
   - `convertToWebP(inputPath: string, outputPath: string, quality?: number): Promise<void>`
   - `addWatermark(basePath: string, watermarkPath: string): Promise<Buffer>`
4. Wire the module into my Express route at `src/routes/upload.ts`.
5. Only use methods and types that are present in `lib/sharp/index.d.ts` and documented in `USAGE.md`.
6. Do not install the published `sharp` npm package; import from `lib/sharp/index.js` instead.
7. Show the final contents of each modified file.

License and credit

The JavaScript source and TypeScript definitions in source/ are dual-licensed:

• Apache-2.0 (.js implementation files) - Copyright 2013 Lovell Fuller and others.
• MIT (index.d.ts type definitions) - Copyright 2017 François Nguyen and others.

Upstream repository and full documentation: https://sharp.pixelplumbing.com
npm: sharp on npmjs.com

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

ImageMagick Node.js Image Processing Plugin

Automation, Utilities & Developer Tools

무료