Jimp (JavaScript Image Manipulation Program)

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... Not supported

  cause Attempting to use `require()` in an ES Module context (e.g., in a `type: "module"` project) for a package that is primarily ESM or has a main ESM export.
  fix Change `const { Jimp } = require('jimp');` to `import { Jimp } from 'jimp';`.

• TypeError: Jimp.read is not a function

  cause Incorrect import of the Jimp class, often caused by using a default import (`import Jimp from 'jimp'`) when `Jimp` is a named export, or trying to access a static method on an incorrectly imported object.
  fix Ensure you are using the named import: `import { Jimp } from 'jimp';`.

• TypeError: Cannot read properties of undefined (reading 'write')

  cause Attempting to call `.write()` or other manipulation methods on an image object that has not been `await`ed, or if `Jimp.read` failed to return an image.
  fix Always `await` asynchronous Jimp operations, especially `Jimp.read()`: `const image = await Jimp.read('path/to/image.png');`

Warnings

• breaking Starting from `v1.2.0`, most plugins (e.g., blur, color, print) are no longer included by default with the main `jimp` package. To use these functionalities, you must explicitly import and add them to a custom Jimp instance.
  Fix: Initialize Jimp with desired plugins: `import Jimp from 'jimp/browser'; import { blur } from '@jimp/plugin-blur'; const customJimp = Jimp.extend(blur); await customJimp.read(...)` or `import { Jimp } from 'jimp'; Jimp.extend(blur);`
• breaking The `brightness` function behavior changed in `v1.1.2` to align with standard CSS brightness implementations. Previously, it used an inverted multiplication. A value of `1` now means no change, with values above `1` increasing brightness.
  Fix: Review existing code using `brightness` and adjust the numeric argument (e.g., a previous `0.5` might now be `1.5` for similar brightening, or `0.5` for dimming).
• gotcha Older versions of Jimp (before `v1.1.4`) often required importing from `jimp/browser` specifically for browser environments to ensure correct bundler integration. While improved, some older configurations might still encounter issues.
  Fix: For new projects, prefer `import { Jimp } from 'jimp';` and rely on modern bundlers to pick up the correct export. If issues persist in a browser context, consider `import Jimp from 'jimp/browser';` or refer to your bundler's configuration.
• gotcha When working with `jimp` in ESM projects (e.g., Node.js with `"type": "module"` or bundlers), ensure you use `import` statements. Attempting to use `require()` might lead to errors about `require is not defined`.
  Fix: Always use `import { Jimp } from 'jimp';` and `await` for asynchronous operations like `Jimp.read` and `image.write`.

Install

• npm install jimp npm
• yarn add jimp yarn
• pnpm add jimp pnpm

Imports

• Jimp
  wrong:

  const Jimp = require('jimp');

  correct:

  import { Jimp } from 'jimp';

  While CommonJS `require` works, ESM `import` is preferred in modern Node.js environments (>=18). The Jimp class is a named export.
• Jimp (default)
  wrong:

  import Jimp from 'jimp';

  correct:

  import Jimp from 'jimp/browser';

  For browser-specific builds or older bundlers, explicitly importing from `jimp/browser` was common. As of v1.1.4, bundler integration improved, allowing `import { Jimp } from 'jimp'` to often work correctly in browser contexts too, but `jimp/browser` remains an option for direct default imports.
• Jimp.read
  wrong:

  import Jimp from 'jimp';
  const image = await Jimp.read('path/to/image.png');

  correct:

  import { Jimp } from 'jimp';
  const image = await Jimp.read('path/to/image.png');

  Jimp.read is a static method of the named `Jimp` class. Ensure you use the named import for `Jimp`.
• JimpType

  import type { JimpType } from '@jimp/types';

  For advanced TypeScript usage, you might import specific types from the `@jimp/types` package, although `Jimp` itself ships with types.

Quickstart

This quickstart demonstrates how to read an image, perform common manipulations like resizing, converting to grayscale, adding text, and saving the output to a new file. It includes basic error handling and uses modern ESM syntax.

import { Jimp } from 'jimp';
import path from 'path';
import fs from 'fs/promises';

async function processImage() {
  const inputPath = path.resolve('./input.png');
  const outputPath = path.resolve('./output-processed.jpg');
  const fontPath = path.resolve(__dirname, '../../node_modules/@jimp/plugin-print/fonts/open-sans/open-sans-16-black/open-sans-16-black.fnt'); // Example font path

  try {
    // Ensure input.png exists for demonstration
    // For a real app, you'd fetch or use an existing file
    // await fs.writeFile(inputPath, Buffer.from('...', 'base64')); // Example: write a placeholder image

    const image = await Jimp.read(inputPath); // Read the image
    
    // Resize, grayscale, and add text
    const font = await Jimp.loadFont(fontPath);
    
    image
      .resize(300, Jimp.AUTO) // resize to 300px width, auto height
      .quality(80) // set JPEG quality
      .greyscale() // set greyscale
      .print(font, 10, 10, 'Hello Jimp!') // add text
      .write(outputPath); // save

    console.log(`Image processed and saved to ${outputPath}`);
  } catch (error) {
    console.error('Error processing image:', error);
  }
}

// Create a dummy input.png for the quickstart if it doesn't exist
async function createDummyImage() {
  const dummyImagePath = path.resolve('./input.png');
  if (!await fs.stat(dummyImagePath).catch(() => false)) {
    const dummyImage = await new Jimp(100, 100, 0xFF0000FF); // 100x100 red image
    await dummyImage.write(dummyImagePath);
    console.log(`Created dummy image at ${dummyImagePath} for quickstart.`);
  }
}

createDummyImage().then(() => processImage());