namespace

bun.Image

namespace Image

  • interface ConstructorOptions

    • autoOrient?: boolean

      Apply EXIF Orientation (JPEG) before any other operation.

    • maxPixels?: number

      Reject inputs whose width × height exceeds this many pixels. The check runs after the header is read but before any pixel buffer is allocated, so a tiny file claiming a huge canvas is refused cheaply. A decoded image takes 4 bytes per pixel, which is 1 GiB at the default. A PNG of 32 KiB can decode to that size. Decoding a PNG that is one very wide row needs up to 20 bytes of memory per pixel, 5 GiB at the default. For untrusted input, set this to the largest image you accept.

  • interface Metadata

  • interface ModulateOptions

    • brightness?: number

      Multiplier; 1 leaves brightness unchanged.

    • saturation?: number

      0 = greyscale, 1 = unchanged, >1 = more saturated.

  • interface ResizeOptions

    • filter?: Filter

      Resampling kernel.

    • fit?: 'fill' | 'inside'

      "fill" stretches to exactly width×height. "inside" preserves aspect ratio so the result fits within width×height.

    • withoutEnlargement?: boolean

      Never upscale — if the source is already smaller, leave it.

  • type ErrorCode =
    | 'ERR_IMAGE_FORMAT_UNSUPPORTED'
    | 'ERR_IMAGE_TOO_MANY_PIXELS'
    | 'ERR_IMAGE_DECODE_FAILED'
    | 'ERR_IMAGE_ENCODE_FAILED'
    | 'ERR_IMAGE_UNKNOWN_FORMAT'
    | 'ERR_OUT_OF_MEMORY'
    | 'ERR_INVALID_STATE'

    Stable error.code values set on rejections from Bun.Image terminals. Branch on these instead of parsing the message.

    • ERR_IMAGE_FORMAT_UNSUPPORTED — the requested format isn't available on this machine (HEIC/AVIF without the OS codec, TIFF on Linux). Catch this to fall back to a portable format.
    • ERR_IMAGE_TOO_MANY_PIXELS — header dimensions or resize output exceed maxPixels, a row of a PNG takes 4 GiB or more, or a path-backed input is over the 256 MiB cap.
    • ERR_IMAGE_DECODE_FAILED / ERR_IMAGE_ENCODE_FAILED — codec error. A damaged JPEG that libjpeg-turbo decodes with only a warning (stray bytes, a missing end marker, truncated scan data) does not reject. Blocks with no data come back flat grey. A PNG with a wrong CRC or Adler-32 does not reject either: Bun verifies neither. A PNG that ends before its last row, or inside the data of the IDAT chunk that holds it, rejects.
    • ERR_IMAGE_UNKNOWN_FORMAT — input bytes didn't match any sniffer.
    • ERR_OUT_OF_MEMORY — there is no memory for the image, or for a buffer that its decode or encode needs.
    • ERR_INVALID_STATE — the input ArrayBuffer was transferred between construction and the terminal call.
    • File-backed inputs surface the underlying syscall code (ENOENT, EACCES, …) directly.
  • type Filter =
    | 'nearest'
    | 'box'
    | 'bilinear'
    | 'linear'
    | 'cubic'
    | 'mitchell'
    | 'lanczos2'
    | 'lanczos3'
    | 'mks2013'
    | 'mks2021'
  • type Format =
    | 'jpeg'
    | 'png'
    | 'webp'
    | 'heic'
    | 'avif'
    | 'bmp'
    | 'tiff'
    | 'gif'

    bmp/tiff/gif are decode-only — metadata().format may report them but there are no .bmp()/.tiff()/.gif() encoder methods. tiff decode rejects with error.code === "ERR_IMAGE_FORMAT_UNSUPPORTED" on Linux; gif decodes the first frame everywhere.