Constructor
Sharp
Emits: Sharp#event:info, Sharp#event:warning
new Sharp([input], [options])
Constructor factory to create an instance of sharp, to which further methods are chained.
JPEG, PNG, WebP, GIF, AVIF or TIFF format image data can be streamed out from this object.
When using Stream based output, derived attributes are available from the info event.
Non-critical problems encountered during processing are emitted as warning events.
Implements the stream.Duplex class.
When loading more than one page/frame of an animated image,
these are combined as a vertically-stacked “toilet roll” image
where the overall height is the pageHeight multiplied by the number of pages.
Throws:
ErrorInvalid parameters
Example
sharp('input.jpg') .resize(300, 200) .toFile('output.jpg', function(err) { // output.jpg is a 300 pixels wide and 200 pixels high image // containing a scaled and cropped version of input.jpg });Example
// Read image data from remote URL,// resize to 300 pixels wide,// emit an 'info' event with calculated dimensions// and finally write image data to writableStreamconst { body } = await fetch('https://...');const readableStream = Readable.fromWeb(body);const transformer = sharp() .resize(300) .on('info', ({ height }) => { console.log(`Image height is ${height}`); });readableStream.pipe(transformer).pipe(writableStream);Example
// Web Streams API, requires Node.js >= 24.15.0import { Duplex } from 'node:stream';
const { body } = await fetch('https://...');const transformer = Duplex.toWeb( sharp().resize(300), { readableType: 'bytes' });body.pipeThrough(transformer).pipeTo(writable);Example
// Create a blank 300x200 PNG image of semi-translucent red pixelssharp({ create: { width: 300, height: 200, channels: 4, background: { r: 255, g: 0, b: 0, alpha: 0.5 } }}).png().toBuffer().then( ... );Example
// Convert an animated GIF to an animated WebPawait sharp('in.gif', { animated: true }).toFile('out.webp');Example
// Read a raw array of pixels and save it to a pngconst input = Uint8Array.from([255, 255, 255, 0, 0, 0]); // or Uint8ClampedArrayconst image = sharp(input, { // because the input does not contain its dimensions or how many channels it has // we need to specify it in the constructor options raw: { width: 2, height: 1, channels: 3 }});await image.toFile('my-two-pixels.png');Example
// Generate RGB Gaussian noiseawait sharp({ create: { width: 300, height: 200, channels: 3, noise: { type: 'gaussian', mean: 128, sigma: 30 } }}).toFile('noise.png');Example
// Generate an image from textawait sharp({ text: { text: 'Hello, world!', width: 400, // max width height: 300 // max height }}).toFile('text_bw.png');Example
// Generate an rgba image from text using pango markup and fontawait sharp({ text: { text: '<span foreground="red">Red!</span><span background="cyan">blue</span>', font: 'sans', rgba: true, dpi: 300 }}).toFile('text_rgba.png');Example
// Join four input images as a 2x2 grid with a 4 pixel gutterconst data = await sharp( [image1, image2, image3, image4], { join: { across: 2, shim: 4 } }).toBuffer();Example
// Generate a two-frame animated image from emojiconst images = ['😀', '😛'].map(text => ({ text: { text, width: 64, height: 64, channels: 4, rgba: true }}));await sharp(images, { join: { animated: true } }).toFile('out.gif');clone() ⇒
Sharp
Take a “snapshot” of the Sharp instance, returning a new instance. Cloned instances inherit the input of their parent instance. This allows multiple output Streams and therefore multiple processing pipelines to share a single input Stream.
Example
// firstWritableStream receives auto-rotated, resized readableStream// secondWritableStream receives auto-rotated, extracted region of readableStream
const pipeline = sharp().rotate();pipeline .clone() .resize(800, 600) .pipe(firstWritableStream);pipeline .clone() .extract({ left: 20, top: 20, width: 100, height: 100 }) .pipe(secondWritableStream);readableStream.pipe(pipeline);Example
// Create a pipeline that will download an image, resize it and format it to different files// Using Promises to know when the pipeline is complete
const sharpStream = sharp();
const promises = [];promises.push( sharpStream .clone() .jpeg({ quality: 100 }) .toFile("originalFile.jpg"));promises.push( sharpStream .clone() .resize({ width: 500 }) .jpeg({ quality: 80 }) .toFile("optimized-500.jpg"));promises.push( sharpStream .clone() .resize({ width: 500 }) .webp({ quality: 80 }) .toFile("optimized-500.webp"));
const res = await fetch("https://www.example.com/some-file.jpg")Readable.fromWeb(res.body).pipe(sharpStream);await Promise.all(promises);