NestJS Enterprise Backend APIs · Ders

Sharp ile Görüntü İşleme İşlem Hatları

Yüklenen görüntüleri arka plan çalışmasına uygun bir işlem hattında yeniden boyutlandırın, dönüştürün ve doğrulayın.

Sharp ile Görüntü İşleme İşlem Hatları, CoddyKit'te ücretsiz bir NestJS Enterprise Backend APIs dersidir. Bu, 4 dersinin 4. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, NestJS Enterprise Backend APIs öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. NestJS Enterprise Backend APIs kursu toplamda 4 dersten oluşur.

Bu dersin bazı bölümleri henüz çevrilmemiş olup İngilizce olarak gösterilmektedir.

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.

Sıkça Sorulan Sorular

“Sharp ile Görüntü İşleme İşlem Hatları” dersi ücretsiz mi?

Evet — “Sharp ile Görüntü İşleme İşlem Hatları” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve NestJS Enterprise Backend APIs kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. NestJS Enterprise Backend APIs kursu toplamda 4 dersten oluşur.

“Sharp ile Görüntü İşleme İşlem Hatları” dersinde ne öğreneceğim?

Yüklenen görüntüleri arka plan çalışmasına uygun bir işlem hattında yeniden boyutlandırın, dönüştürün ve doğrulayın. NestJS Enterprise Backend APIs ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

NestJS Enterprise Backend APIs öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te NestJS Enterprise Backend APIs, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 4. dersidir.

“Sharp ile Görüntü İşleme İşlem Hatları” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu NestJS Enterprise Backend APIs dersinde kod yazıp çalıştırabilir miyim?

Evet. Her NestJS Enterprise Backend APIs dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

Multer Aracılarıyla Çok Parçalı Yüklemeler
StreamableFile ile Büyük Yanıtları Akışa Alma
Önceden İmzalanmış URL'lerle Doğrudan S3'e Yükleme
Sharp ile Görüntü İşleme İşlem Hatları

← NestJS Enterprise Backend APIs Sayfasına Dön