image-manifest

A cross-platform Node.js tool that converts images to the required format, generates a file structure in JSON, and resizes them if necessary. It can be used from the command line, a minimal local Web UI, or as a library. Useful for static websites, galleries, and automation.

Requires Node.js 22 or newer. Run npx image-manifest --help to see all available options.

📖 Usage

Create an img-src folder

mkdir img-src

Place images inside img-src

# Interactive CLI (always asks for options)
npx image-manifest@latest -i

# Browser UI
npx image-manifest@latest --ui

Running npx image-manifest@latest without arguments uses a discovered configuration file if one exists; otherwise, it starts interactive mode.

💻 Command-line options

Option	Description	Default
--src, -s	Source folder name (must exist)	img-src
--dist, -d	Result folder name	img-dist
--format, -f	Output format: webp, jpg, png, avif, or keep original (original)	webp
--json, -j	Output JSON filename (or --no-json to skip)	null
--width, -W	Maximum image width in pixels	null
--height, -H	Maximum image height in pixels	null
--concurrency, -c	Maximum number of concurrent image processing tasks	5
--include-size	Include image dimensions (width and height) in the JSON manifest	false
--manifest-only	Only generate JSON manifest, skip image conversion	false
--no-progress	Disable the progress bar	false
--continue-on-error	Continue processing even if some images fail	false
--interactive, -i	Force interactive mode even if arguments are provided	false
--ui	Open a local Web UI in the browser	false

✨ Examples

# Convert all images to webp (default) and generate manifest
npx image-manifest --json static-images --format original

# Resize images to max height 2000px, use custom source folder
npx image-manifest --src sources --height 2000

# Only create a JSON manifest from existing images (no processing)
npx image-manifest --manifest-only --json gallery --src myimages

# Continue processing even if some images fail, and skip progress bar
npx image-manifest --continue-on-error --no-progress --json report

# Run interactive mode (asks for every option)
npx image-manifest --interactive

# Open the local Web UI
npx image-manifest --ui

🌐 Local Web UI

Run npx image-manifest --ui to open the local interface in your browser. Enter the source folder; the output folder is suggested as <source>-dist and can be changed. Choose WebP, AVIF, JPG, PNG, or Original, then set independent maximum width and height limits in pixels. Leave both limits at their defaults (1000 px) or adjust them; the aspect ratio is preserved and the image is only resized when it exceeds a limit. Click Start to begin. While processing, the same button becomes Stop processing: the current image finishes, and the remaining images are skipped. The Close button is unavailable during processing.

The server binds to 127.0.0.1 on a randomly selected port. The UI follows the browser's preferred language when English, Russian, Ukrainian, or German is available (otherwise it uses English) and follows the system/browser light or dark color-scheme preference. After closing the UI, run npx image-manifest --ui again to reopen it. The browser does not always expose a dropped folder's full path, so pasting the path manually is supported and remains the most reliable option.

⚙️ Configuration file

You can store your options in a configuration file instead of passing CLI arguments every time. Create any of these files (searched in the current directory and up):

• .image-manifestrc.json
• .image-manifestrc
• a "image-manifest" property in package.json

Example .image-manifestrc.json:

{
  "src": "my-images",
  "format": "webp",
  "json": "gallery",
  "width": 1200,
  "includeSize": true
}

When you run npx image-manifest without any arguments, it will automatically pick up the configuration file if one exists. Otherwise it starts interactive mode.

📦 Programmatic API

You can also use image-manifest as a library in your own scripts.

import { run } from 'image-manifest';

await run({
  src: 'photos',
  dist: 'output',
  format: 'webp',
  json: 'manifest',
  width: 800,
  height: null,
  concurrency: 4,
  includeSize: true,
  continueOnError: true,
  // manifestOnly: true  // uncomment to skip conversion
});

TypeScript users can import the manifest types:

import type { ImageManifest, ImageFile } from 'image-manifest';

You can also import individual utilities for finer control:

import { imageProcessing } from 'image-manifest/image-processing';
import { convertToWebp } from 'image-manifest/to-webp';
import { isImage } from 'image-manifest/is-image';
import { collectImages } from 'image-manifest/collect-images';

convertToWebp accepts a file path or Buffer, returns a WebP Buffer and image dimensions, and limits the longest side to 1000 pixels by default:

const { buffer, width, height } = await convertToWebp(input, 1000);

The source and output directories must be different. The library aborts when they are equal or when one contains the other.

To enable debug output, set the DEBUG environment variable:

DEBUG=image-manifest:* npx image-manifest --src photos