High performance Node.js image processing

Common errors

• Error: Cannot find module 'sharp'

  cause The 'sharp' package was not installed successfully or is missing from `node_modules`.
  fix Run `npm install sharp` or `yarn add sharp` to ensure the package and its native dependencies are correctly installed.

• Error: The 'sharp' module is incompatible with the current Node.js version.

  cause You are using a version of Node.js that is not supported by your installed 'sharp' version, often due to a major sharp version upgrade.
  fix Check the `engines` field in sharp's `package.json` or consult the documentation for compatible Node.js versions. Upgrade Node.js accordingly (e.g., to 20.9.0+ for sharp >= 0.35.0).

• Error: Input file is not a valid image

  cause The input file provided to `sharp()` is either corrupted, not a supported image format, or its path is incorrect.
  fix Verify that the input file exists, is readable, and is a valid image in a format supported by sharp (JPEG, PNG, WebP, etc.).

• RangeError: Allocation failed - JavaScript heap out of memory

  cause Processing very large images or performing complex operations on multiple images simultaneously can exhaust Node.js's memory limit.
  fix For very large images, consider streaming input/output or increasing Node.js's memory limit using `node --max-old-space-size=4096 script.js` (adjust `4096` as needed).

• Error: EACCES: permission denied, open 'output.webp'

  cause The Node.js process does not have the necessary write permissions for the specified output directory or file.
  fix Ensure that the directory where you are trying to save the output file has write permissions for the user running the Node.js process. You might need to change directory permissions or choose a different output path.

Warnings

• breaking Sharp v0.35.0 and later require Node.js 20.9.0 or higher. Node.js 18 support is dropped.
  Fix: Upgrade your Node.js environment to version 20.9.0 or later.
• breaking The automatic `install` script in `package.json` for compiling from source has been removed.
  Fix: If you need to compile sharp from source, use `npm run build` or `yarn build` explicitly.
• breaking AVIF output quality metrics have changed from `ssim` to `iq` (SSIMULACRA2-based) in v0.35.0.
  Fix: Update your AVIF quality configuration, replacing `ssim` parameters with `iq` when using `.avif()`.
• breaking The `failOnError` constructor property has been removed.
  Fix: Sharp will now throw errors by default for invalid inputs. Ensure your code handles exceptions thrown by sharp operations.
• breaking The `paletteBitDepth` property is no longer included in the `metadata` response.
  Fix: Remove or update any code that relies on accessing `paletteBitDepth` from the image metadata object.

Install

• npm install sharp npm
• yarn add sharp yarn
• pnpm add sharp pnpm

Imports

• sharp
  wrong:

  const sharp = require('sharp')

  correct:

  import sharp from 'sharp'

Quickstart

Resizes an input image (or creates a placeholder if none exists) to 300x200 pixels, converts it to WebP format with 80% quality, and saves it to 'output.webp'.

import sharp from 'sharp';
import { createWriteStream, readFileSync } from 'fs';

async function processImage() {
  const inputPath = 'input.jpg'; // Replace with your input image path
  const outputPath = 'output.webp';

  // Create a dummy input image if it doesn't exist for demonstration
  try {
    readFileSync(inputPath);
  } catch (error) {
    const placeholderImage = Buffer.from('<svg width="100" height="100" viewBox="0 0 100 100"><rect width="100" height="100" fill="#f0f0f0" /><text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-size="20" fill="#333">Hello</text></svg>');
    await sharp(placeholderImage)
      .toFile(inputPath);
    console.log(`Created dummy input.jpg at ${inputPath}`);
  }

  try {
    await sharp(inputPath)
      .resize(300, 200, { fit: 'cover' })
      .webp({ quality: 80 })
      .toFile(outputPath);
    console.log(`Image processed and saved to ${outputPath}`);
  } catch (error) {
    console.error(`Error processing image: ${error}`);
  }
}

processImage();