fake-image

Generate fake image files and buffers. Useful for generating fixtures for unit tests for image libraries. Supports PNG, JPEG, GIF, WebP, SVG, and many other image formats.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install

Install with npm:

$ npm install --save fake-image

Important!

Most formats require FFmpeg. See Prerequisites for installation details.

Usage

import { fakeImage, fakeImageFile } from 'fake-image';

const buffer = await fakeImage('example.png', {
  width: 640,
  height: 480,
  color: 'royalblue'
});

await fakeImageFile('fixtures/example.webp', {
  width: 320,
  height: 240
});

API

fakeImage

Creates a solid-color image and returns its encoded contents as a buffer. The extension of filepath determines the image format; the path is used only for format selection and no file is created.

fakeImage(filepath: string, options: CreateFakeImageFileOptions): Promise<Buffer>

Params

• filepath {String}: A filename or filepath with a supported extension. Extension matching is case-insensitive.
• options {Object}: Image generation options.
• options.width {Number}: Image width in pixels. Must be a positive integer.
• options.height {Number}: Image height in pixels. Must be a positive integer.
• options.color {String}: Fill color. Defaults to black. FFmpeg color names, hexadecimal colors, and other color expressions supported by the installed FFmpeg build may be used for formats generated through FFmpeg.

Returns

• {Promise}: Resolves with the encoded image data.

Example

const png = await fakeImage('placeholder.png', {
  width: 800,
  height: 600,
  color: '#663399'
});

const svg = await fakeImage('avatar.svg', {
  width: 128,
  height: 128,
  color: 'tomato'
});

An invalid width or height throws a RangeError. An unsupported or missing extension throws an Error. For formats generated through FFmpeg, the promise rejects if FFmpeg cannot start or exits unsuccessfully.

fakeImageFile

Creates a solid-color image and writes it to filepath. Missing parent directories are created automatically.

fakeImageFile(filepath: string, options: CreateFakeImageFileOptions): Promise<void>

Params

• filepath {String}: Destination filepath. Its extension determines the image format.
• options {Object}: Accepts all fakeImagefakeImage options.
• options.width {Number}: Image width in pixels. Must be a positive integer.
• options.height {Number}: Image height in pixels. Must be a positive integer.
• options.color {String}: Fill color. Defaults to black.

Returns

• {Promise}: Resolves after the destination file has been written.

Example

await fakeImageFile('fixtures/images/banner.jpg', {
  width: 1200,
  height: 400,
  color: 'navy'
});

File creation errors, invalid dimensions, unsupported extensions, and FFmpeg errors reject the promise.

Options

Both methods accept the following options:

| Option | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | width | number | Yes | — | Image width in pixels. Must be a positive integer. | | height | number | Yes | — | Image height in pixels. Must be a positive integer. | | color | string | No | black | Solid fill color used for every pixel. |

Supported formats

• SVG: .svg, .svgz
• TIFF: .tif, .tiff
• DDS: .dds
• KTX: .ktx
• KTX2: .ktx2
• PSD: .psd
• ffmpeg-based image formats:
  • .avif, .avifs
  • .bmp, .dib
  • .gif
  • .ico, .cur
  • .j2c, .j2k, .jpc
  • .jp2, .jpf, .jpm, .mj2
  • .jfi, .jfif, .jif, .jpe, .jpeg, .jpg
  • .pam, .pbm, .pfm, .pgm, .pnm, .ppm
  • .png
  • .tga, .icb, .vda, .vst
  • .webp

Notes

• .svgz is written as compressed SVG.
• SVG color values are escaped before they are inserted into the generated markup.
• .cur is written as an ICO-style file, adjusted to cursor type, and uses the top-left pixel as its hotspot.
• .avifs produces a single-frame AVIF image.
• TIFF, DDS, KTX, KTX2, and PSD files contain uncompressed pixel data created from an FFmpeg-generated RGBA image.
• Calling fakeImage() does not write to filepath; call fakeImageFile() when a file is needed.

Prerequisites

Node.js 15 or newer is the practical minimum. This package uses modern Node.js APIs including String.prototype.replaceAll, fs.promises.rm, BigInt buffer methods, and node: imports.

All formats except .svg and .svgz require the ffmpeg executable to be available on PATH. Install it with the appropriate command for your platform:

• macOS: brew install ffmpeg
• Ubuntu or Debian: sudo apt install ffmpeg
• Fedora: enable RPM Fusion, then run sudo dnf install ffmpeg
• Windows: winget install Gyan.FFmpeg

Confirm that FFmpeg is available by running:

ffmpeg -version

AVIF and AVIFS output requires an FFmpeg build with the libsvtav1 encoder. WebP output requires libwebp. Other FFmpeg-based formats require their corresponding encoders. Run ffmpeg -encoders to see the encoders available in your installation.

No separate ImageMagick, gzip command, or third-party JavaScript runtime library is required. The process must have access to the operating system's temporary directory and write permission for paths passed to fakeImageFile().

About

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Related projects

You might also be interested in these projects:

• fake-audio: Generate fake audio files and buffers. Useful for generating fixtures for unit tests for audio… more | homepage
• fake-video: Generate fake video files and buffers. Useful for generating fixtures for unit tests for video… more | homepage
• video-size: Get the width and height of a video. | homepage

Author

Jon Schlinkert

• GitHub Profile
• X Profile
• LinkedIn Profile

License

Copyright © 2026, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.8.0, on August 27, 2026.