pixl-resize

pixl-resize is a small, purpose-built image resizer for Node.js, designed to process user avatar images for web apps.

• Pure JavaScript, CommonJS
• Buffer in, Buffer out
• JPEG, PNG, GIF, and BMP input only
• PNG output only
• Area sampling for shrink operations, bilinear for enlargement
• No dependencies

Install

npm install pixl-resize

Usage

const fs = require('node:fs');
const resize = require('pixl-resize');

const input = fs.readFileSync('input.jpg');

const output = resize(input, {
  width: 320,
  height: 240,
  mode: 'cover'
});

fs.writeFileSync('output.png', output);

API

resize(inputBuffer, options)

Returns a PNG Buffer.

Options:

• width (number, required): Target box width.
• height (number, required): Target box height.
• mode (string, optional): contain or cover. Defaults to contain.
• fit (string, optional): Alias for mode.

Behavior:

• Input must be a Buffer.
• Output is always a PNG Buffer.
• Internal pixel format is RGBA.
• Output PNG is 24-bit RGB when fully opaque, otherwise 32-bit RGBA.
• cover crops from the center to fill the requested size.
• contain does not pad or letterbox. Instead, the final PNG dimensions are reduced to fit inside the requested box while preserving aspect ratio.
• Downscaling uses a box filter over the full source footprint of each output pixel to avoid aliasing on large reductions.

Example:

const output = resize(input, {
  width: 200,
  height: 200,
  mode: 'contain'
});

If the source is 400x200, the result will be 200x100, not 200x200 with padding.

Supported Input Variants

The package is intentionally small, but it handles common real-world files:

• JPEG: 8-bit baseline and progressive JPEG, grayscale, YCbCr, and common Adobe RGB/CMYK/YCCK variants.
• PNG: Non-interlaced PNG with grayscale, RGB, indexed, grayscale+alpha, or RGBA data up to 8-bit samples.
• GIF: First frame only. Animation is ignored.
• BMP: Uncompressed and bitfield BMP in common 1/4/8/16/24/32-bit forms.

Package Layout

Format readers live in separate files under lib/formats/:

• lib/formats/jpeg.js
• lib/formats/png.js
• lib/formats/gif.js
• lib/formats/bmp.js

This keeps the registry small and makes it straightforward to add more formats later.

Notes

• No filesystem access happens inside the module.
• No external npm dependencies are used.
• Very large images are rejected by safety limits to avoid pathological memory usage.
  • Limits are 32768x32768 or 100MP, whichever is hit first.

Development

npm test