Molecule.dev

@molecule/api-image-jimp

Provider bond · image · API (Node) · v1.0.2 · Apache-2.0

Jimp image processing provider for molecule.dev

npm install @molecule/api-image-jimp

npm · Source on GitHub · Implements @molecule/api-image

How it works

@molecule/api-image-jimp is a provider bond on the API (Node) side: it implements the image core interface (@molecule/api-image) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { setProvider } from '@molecule/api-image'
import { provider } from '@molecule/api-image-jimp'

setProvider(provider)

Works with: @molecule/api-image

Reference

Jimp image provider for molecule.dev.

Pure-JavaScript image processing with zero native dependencies. Supports resize, crop, format conversion, thumbnailing, optimization, rotation, flip, and flop operations.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider } from '@molecule/api-image'
import { provider } from '@molecule/api-image-jimp'

setProvider(provider)

Type

provider

Installation

npm install @molecule/api-image-jimp @molecule/api-image jimp

API

Interfaces

JimpConfig

Configuration options for the Jimp image provider.

interface JimpConfig {
  /** Default JPEG quality (1–100). Defaults to `80`. */
  defaultJpegQuality?: number

  /** Default PNG deflate level (0–9). Defaults to `6`. */
  defaultPngDeflateLevel?: number
}

Functions

getSupportedFormats()

Returns the image formats this bond can produce. Never advertises webp/avif.

function getSupportedFormats(): readonly ImageFormat[]

Returns: The list of supported ImageFormats for capability feature-detection.

createProvider(config)

Creates a Jimp-backed image provider.

function createProvider(config?: JimpConfig): ImageProvider
  • config — Optional provider configuration (default quality settings).

Returns: An ImageProvider backed by Jimp.

Constants

SUPPORTED_FORMATS

The ImageFormats this bond can actually decode AND encode. Deliberately EXCLUDES webp and avif: Jimp 1.x ships no codec for either, so this bond must not advertise formats it cannot produce — use @molecule/api-image-sharp when those are required. Callers can read this to feature-detect before requesting a conversion.

const SUPPORTED_FORMATS: readonly ImageFormat[]

provider

The provider implementation, lazily initialized with default config.

const provider: ImageProvider

Core Interface

Implements @molecule/api-image interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-image'
import { provider } from '@molecule/api-image-jimp'

export function setupImageJimp(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-image ^1.0.1

Runtime Dependencies

  • @molecule/api-image

  • jimp

  • WebP and AVIF are NOT supported — Jimp 1.x ships no codec for either. The core ImageFormat union includes them, but this bond does not advertise them: getSupportedFormats() returns only jpeg, png, gif, tiff. Requesting webp/avif as OUTPUT (convert/optimize) or as INPUT (any decode) fails early with a clear, actionable error that names the sharp sibling (for example: jimp does not support the "webp" output format — use @molecule/api-image-sharp for WebP/AVIF. jimp supports: jpeg, png, gif, tiff.), never an opaque mid-pipeline throw. The inherited E2E checklist's "WebP round-trips" item does NOT apply to this bond: feature-detect with getSupportedFormats() and bond @molecule/api-image-sharp when the app touches WebP/AVIF.

  • Pure-JS tradeoff: zero native dependencies (runs anywhere Node runs) but markedly slower and more memory-hungry than sharp on large images — treat sharp as the default and jimp as the no-native-binaries fallback.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

  • Uploading an image through the UI produces the PROCESSED variant where the app uses one (thumbnail/resized/avatar) and it actually renders — check its rendered dimensions or transfer size against the original to confirm processing happened.
  • Common input formats (JPEG, PNG, WebP) all round-trip to a rendered result.
  • A corrupt or non-image file fails with a visible, readable error — not a server crash or a broken-image placeholder that persists.
  • Any UI that shows image metadata (dimensions, size) matches the real file.
  • Where optimization is wired, the served image is materially smaller than the uploaded original.