NestJS Enterprise Backend APIs · Lesson

Image Processing Pipelines with Sharp

Resize, transcode, and validate uploaded images in a background-safe processing pipeline.

Image Processing Pipelines with Sharp is a free NestJS Enterprise Backend APIs lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the NestJS Enterprise Backend APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Sharp for Image Pipelines

When users upload images to your NestJS API, you rarely want to store the raw file as-is. A 12-megapixel phone photo can be 8 MB of JPEG that you serve to mobile clients on slow networks.

Sharp is the de-facto Node.js image processing library. It wraps libvips, a low-level C library that processes images in a streaming, low-memory way.

Fast: 4-5x faster than ImageMagick bindings.
Memory-safe: libvips streams pixels in chunks instead of decoding the whole image into RAM.
Format-rich: reads/writes JPEG, PNG, WebP, AVIF, GIF, TIFF, SVG.

In this lesson you will build a resize-transcode-validate pipeline that is safe to run on uploaded, untrusted images.

The Sharp Pipeline Mental Model

A Sharp instance is a lazy pipeline. Method calls like .resize() and .webp() only queue operations. Nothing is decoded or encoded until you call a terminal method like .toBuffer() or .toFile().

Because it is lazy, you can build the pipeline once and execute it multiple times. The input can be a file path, a Buffer, or a readable stream.

import sharp from 'sharp';

async function run(): Promise<void> {
  // 1x1 red pixel PNG, base64-encoded
  const pngBase64 =
    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
  const input = Buffer.from(pngBase64, 'base64');

  // Pipeline: queue resize + WebP, then execute with toBuffer()
  const output = await sharp(input)
    .resize(64, 64)
    .webp({ quality: 80 })
    .toBuffer();

  console.log('Output bytes:', output.length);
  console.log('Is WebP:', output.slice(8, 12).toString() === 'WEBP');
}

run().catch((err) => console.error(err));

Reading Metadata Before You Trust It

Never resize or store an upload before inspecting it. sharp(input).metadata() reads only the header, so it is cheap and tells you the real format, dimensions, and channel count.

This is your first validation gate. If format is missing or unexpected, the bytes are not a real image regardless of the file extension or the client-supplied MIME type.

import sharp, { Metadata } from 'sharp';

const ALLOWED = new Set(['jpeg', 'png', 'webp', 'avif']);

async function validateImage(buffer: Buffer): Promise<Metadata> {
  const meta = await sharp(buffer).metadata();

  if (!meta.format || !ALLOWED.has(meta.format)) {
    throw new Error(`Unsupported image format: ${meta.format ?? 'unknown'}`);
  }
  if (!meta.width || !meta.height) {
    throw new Error('Image has no readable dimensions');
  }
  return meta;
}

// 1x1 red pixel PNG
const png = Buffer.from(
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
  'base64',
);

validateImage(png)
  .then((m) => console.log(`OK: ${m.format} ${m.width}x${m.height}`))
  .catch((e) => console.error(e.message));

Guarding Against Decompression Bombs

A small file can declare enormous dimensions (a decompression bomb): a 40,000 x 40,000 PNG that is a few KB on disk but allocates billions of pixels when decoded, exhausting memory.

Reject oversized dimensions before decoding, using the header metadata. Also call .limitInputPixels() so libvips itself refuses to fully decode anything above a cap.

Check pixel count from metadata (width * height).
Set a hard libvips cap with limitInputPixels.

import sharp from 'sharp';

const MAX_PIXELS = 24_000_000; // ~24 MP cap

async function safeDecode(buffer: Buffer): Promise<Buffer> {
  const meta = await sharp(buffer).metadata();
  const pixels = (meta.width ?? 0) * (meta.height ?? 0);

  if (pixels > MAX_PIXELS) {
    throw new Error(`Image too large: ${pixels} pixels exceeds ${MAX_PIXELS}`);
  }

  // Hard cap inside libvips as a second line of defence
  return sharp(buffer, { limitInputPixels: MAX_PIXELS })
    .rotate() // auto-orient from EXIF before stripping it
    .toBuffer();
}

safeDecode(Buffer.from('not an image'))
  .then(() => console.log('decoded'))
  .catch((e) => console.error('rejected:', e.message));

Resize Strategies: fit and position

The resize options control how the source maps into the target box. The key option is fit:

cover (default): fills the box, cropping overflow. Great for square avatars.
contain: fits inside the box, padding with background.
inside: shrinks to fit without cropping or padding; never enlarges past the box.
outside: ensures the box is fully covered, may exceed one dimension.

Set withoutEnlargement: true so you never upscale a small original into a blurry larger image.

import sharp from 'sharp';

function buildResize(input: Buffer) {
  return sharp(input).resize({
    width: 512,
    height: 512,
    fit: 'cover',
    position: 'attention', // crop toward the most salient region
    withoutEnlargement: true,
  });
}

export { buildResize };

Transcoding to Modern Formats

Storing uploads as WebP or AVIF cuts bytes dramatically versus JPEG at the same visual quality. A common enterprise pattern: normalize every upload to WebP for delivery and keep one archival original.

Each encoder has its own options. Use effort to trade CPU time for smaller files, and quality for the visual/size balance.

import sharp from 'sharp';

export type Variant = 'thumb' | 'display';

export function transcode(input: Buffer, variant: Variant): Promise<Buffer> {
  const size = variant === 'thumb' ? 160 : 1280;

  return sharp(input)
    .resize({ width: size, height: size, fit: 'inside', withoutEnlargement: true })
    .webp({
      quality: variant === 'thumb' ? 70 : 82,
      effort: 4, // 0 (fast) .. 6 (slow, smallest)
    })
    .toBuffer();
}

Stripping Metadata and Fixing Orientation

Uploaded photos carry EXIF metadata that can include GPS coordinates and device info. By default Sharp strips all metadata on output, which is exactly what you want for privacy.

But EXIF also stores the orientation flag. If you strip metadata without applying it, portrait photos come out sideways. The fix: call .rotate() with no arguments early in the pipeline. It bakes the EXIF orientation into the pixels, then the flag can be safely dropped.

If you must keep an ICC color profile, pass .keepIccProfile() or .withMetadata({ icc: '...' }) while still dropping the rest.

import sharp from 'sharp';

export function normalize(input: Buffer): Promise<Buffer> {
  return sharp(input)
    .rotate() // apply EXIF orientation into the pixels
    .resize({ width: 1080, fit: 'inside', withoutEnlargement: true })
    .keepIccProfile() // preserve color accuracy, drop everything else
    .webp({ quality: 80 })
    .toBuffer(); // EXIF (incl. GPS) is gone from the output
}

Wrapping the Pipeline in a NestJS Service

Isolate all Sharp logic behind an injectable service. Controllers stay thin and the pipeline becomes unit-testable. The service exposes one method that validates, guards, and produces the output variants.

Notice we re-read metadata() from the same buffer; Sharp instances are cheap to create, so building a fresh one per operation is idiomatic.

import { Injectable, BadRequestException } from '@nestjs/common';
import sharp from 'sharp';

const ALLOWED = new Set(['jpeg', 'png', 'webp', 'avif']);
const MAX_PIXELS = 24_000_000;

export interface ProcessedImage {
  thumb: Buffer;
  display: Buffer;
  width: number;
  height: number;
}

@Injectable()
export class ImageProcessingService {
  async process(buffer: Buffer): Promise<ProcessedImage> {
    const meta = await sharp(buffer).metadata();

    if (!meta.format || !ALLOWED.has(meta.format)) {
      throw new BadRequestException('Unsupported image format');
    }
    const pixels = (meta.width ?? 0) * (meta.height ?? 0);
    if (pixels === 0 || pixels > MAX_PIXELS) {
      throw new BadRequestException('Invalid image dimensions');
    }

    const base = () =>
      sharp(buffer, { limitInputPixels: MAX_PIXELS }).rotate();

    const [thumb, display] = await Promise.all([
      base().resize({ width: 160, height: 160, fit: 'cover' }).webp({ quality: 70 }).toBuffer(),
      base().resize({ width: 1280, fit: 'inside', withoutEnlargement: true }).webp({ quality: 82 }).toBuffer(),
    ]);

    return { thumb, display, width: meta.width!, height: meta.height! };
  }
}

Keeping It Background-Safe with a Queue

Image processing is CPU-bound. Doing it inline in the HTTP request blocks the Node event loop and stalls other requests. The enterprise pattern is to offload to a background worker.

The controller stores the raw upload and enqueues a job (e.g. BullMQ on Redis).
A worker process consumes the job, runs the Sharp pipeline, and writes the variants.
The API responds 202 Accepted immediately with a job/asset id.

This keeps request latency low and lets you scale workers independently of web dynos. Sharp also releases the event loop during native work, but heavy concurrent jobs still belong off the request path.

import { Injectable } from '@nestjs/common';
import { InjectQueue } from '@nestjs/bullmq';
import { Queue } from 'bullmq';

export interface ImageJob {
  assetId: string;
  storageKey: string; // where the raw upload lives
}

@Injectable()
export class ImageUploadService {
  constructor(@InjectQueue('image') private readonly queue: Queue) {}

  async enqueue(job: ImageJob): Promise<void> {
    await this.queue.add('process', job, {
      attempts: 3,
      backoff: { type: 'exponential', delay: 2000 },
      removeOnComplete: true,
    });
  }
}

Streaming Large Files Without Buffering

Calling .toBuffer() holds the entire output in memory. For large originals or high-throughput pipelines, stream instead: pipe an upload stream into a Sharp transform and pipe the result out to storage.

A Sharp instance is itself a duplex stream, so it slots directly into Node's stream pipeline. This keeps peak memory bounded regardless of image size.

import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
import sharp from 'sharp';

export async function streamResize(
  inputPath: string,
  outputPath: string,
): Promise<void> {
  const transform = sharp()
    .rotate()
    .resize({ width: 1280, fit: 'inside', withoutEnlargement: true })
    .webp({ quality: 82 });

  await pipeline(
    createReadStream(inputPath),
    transform,
    createWriteStream(outputPath),
  );
}

Tuning Concurrency and Caches

Sharp uses a thread pool for the heavy native work. Under load you can tune it globally:

sharp.concurrency(n) sets libvips worker threads per operation. In a worker process, setting it to the number of cores is typical; in a busy web process, lowering it prevents CPU starvation of request handling.
sharp.cache() controls the libvips operation cache. For one-shot, untrusted uploads you often disable it to bound memory.

Set these once at process startup, not per request.

import sharp from 'sharp';
import os from 'node:os';

// Call once during bootstrap (e.g. in main.ts before app.listen)
export function configureSharp(): void {
  sharp.concurrency(Math.max(1, os.cpus().length - 1));
  sharp.cache({ memory: 64, files: 0, items: 100 });
  console.log('Sharp concurrency:', sharp.concurrency());
}

Quick Check: Orientation and Privacy

A user reports that portrait photos from their iPhone appear rotated 90 degrees after your pipeline, and your security team also requires that GPS data never be stored. Which single change to the pipeline best addresses both?

Recap: A Production Image Pipeline

You built a safe, modern image pipeline with Sharp in NestJS. The essentials:

Validate first: read metadata() and allow only known formats with real dimensions.
Guard memory: reject decompression bombs by pixel count and set limitInputPixels.
Normalize: .rotate() to apply EXIF orientation, then rely on default stripping to drop GPS/EXIF.
Resize and transcode: choose the right fit, use withoutEnlargement, and output WebP/AVIF variants.
Stay off the request path: enqueue CPU-bound work to a background worker and return 202.
Stream large files and tune concurrency/cache once at startup.

This combination gives you fast, private, memory-safe media handling that scales independently of your HTTP tier.

Frequently asked questions

Is the “Image Processing Pipelines with Sharp” lesson free?

Yes — the full text of “Image Processing Pipelines with Sharp” is free to read here on the web, and the NestJS Enterprise Backend APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the NestJS Enterprise Backend APIs course, upgrade to CoddyKit PRO.

What will I learn in “Image Processing Pipelines with Sharp”?

Resize, transcode, and validate uploaded images in a background-safe processing pipeline. You practise NestJS Enterprise Backend APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start NestJS Enterprise Backend APIs?

No prior experience is required. NestJS Enterprise Backend APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Image Processing Pipelines with Sharp” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this NestJS Enterprise Backend APIs lesson?

Yes. Every NestJS Enterprise Backend APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Multipart Uploads with Multer Interceptors
Streaming Large Responses with StreamableFile
Direct-to-S3 Uploads with Presigned URLs
Image Processing Pipelines with Sharp

← Back to NestJS Enterprise Backend APIs