image-meta

library0.2.2jsnpmunverified

image-meta is a lightweight, pure JavaScript library designed for detecting the type and dimensions (width, height, orientation) of various image formats directly from a `Buffer` or `Uint8Array`. It supports common formats like JPEG, PNG, GIF, BMP, WebP, SVG, ICO, AVIF, HEIC, and TIFF. The package is currently at version 0.2.2 and appears to have a relatively active, though not rapid, release cadence, with updates for new image formats like AVIF and HEIC in recent minor versions. Its key differentiator is its minimal footprint and pure JavaScript implementation, making it suitable for both Node.js and browser environments (when dealing with byte arrays). It is based on the `image-size` library but aims for a more focused and potentially more modern approach.

serialization

npm install image-meta

github ↗package ↗

INSTALL

IMPORT

SIG · IMAGE-META

image-meta

serializationjavascriptv0.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

imageMeta

✓ import { imageMeta } from 'image-meta';

✗ const { imageMeta } = require('image-meta');

Primarily designed for ESM usage. While CommonJS `require` might work in some environments, ESM `import` is the idiomatic and recommended approach for modern JavaScript and TypeScript projects.

imageMeta (type)

✓ import type { ImageMeta } from 'image-meta';

Import the `ImageMeta` type for strong typing of the returned metadata object in TypeScript projects.

Demonstrates fetching an image, converting its response to a Uint8Array, and using `imageMeta` to extract metadata like type, width, height, and orientation. Includes error handling.

import { imageMeta } from 'image-meta'; async function getImageMetadata(imageUrl: string) { try { const response = await fetch(imageUrl); if (!response.ok) { throw new Error(`Failed to fetch image: ${response.statusText}`); } // For Node.js, you might need 'node-fetch' and res.buffer() // For browser, you'd use res.arrayBuffer() and then new Uint8Array() const arrayBuffer = await response.arrayBuffer(); const data = new Uint8Array(arrayBuffer); const meta = imageMeta(data); console.log(`Image Type: ${meta.type}`); console.log(`Dimensions: ${meta.width}x${meta.height}`); if (meta.orientation) { console.log(`Orientation: ${meta.orientation}`); } return meta; } catch (error) { console.error('Error detecting image meta:', error); throw error; // Re-throw to indicate failure } } // Example usage with a placeholder URL getImageMetadata('https://example.com/some-image.jpg') .then(meta => console.log('Successfully retrieved meta:', meta)) .catch(err => console.error('Overall error:', err));

Debug

Known issues

gotcha`imageMeta` throws an error if the input data is not a `Buffer`/`Uint8Array`, or if the data is invalid/unreadable, or if the image type cannot be determined. Developers must wrap calls to `imageMeta` in a `try/catch` block to handle these potential runtime errors gracefully.

fix

Always use `try { imageMeta(data) } catch (e) { /* handle error */ }` around calls to `imageMeta`.

affects: >=0.1.0

gotchaThe package expects raw image buffer data. If fetching from a URL in a browser environment, ensure you convert the `Response` to an `ArrayBuffer` and then to a `Uint8Array`. In Node.js, libraries like `node-fetch` often provide a `buffer()` method.

fix

For browser: `await fetch(url).then(res => res.arrayBuffer()).then(buf => new Uint8Array(buf))`. For Node.js with `node-fetch`: `await fetch(url).then(res => res.buffer())`.

affects: >=0.1.0

gotchaThe `orientation` property is only present for image types that support EXIF orientation data (primarily JPEG) and when such data exists. For other formats or images without EXIF, `orientation` will be undefined.

fix

When accessing `meta.orientation`, always check for its existence: `if (meta.orientation) { /* use orientation */ }`.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Expected a Buffer or Uint8Array

The input to `imageMeta` was not a `Buffer` (Node.js) or `Uint8Array` (browser/Node.js). Common mistakes include passing a string, a plain `ArrayBuffer`, or a `Blob` directly.

fix

Ensure your image data is converted to a `Buffer` (Node.js) or `Uint8Array` before passing it to `imageMeta`. For `ArrayBuffer`, use `new Uint8Array(arrayBuffer)`.

Error: Invalid image data or unsupported type

The provided `Buffer` or `Uint8Array` does not contain valid image data, is corrupted, or represents an image format not currently supported by `image-meta`.

fix

Verify the integrity of your image data source. Check if the image format is listed as supported by `image-meta`. Wrap calls in `try/catch` to gracefully handle these errors.

ReferenceError: imageMeta is not defined

Incorrect import statement or attempting to use `imageMeta` in a CommonJS environment without proper transpilation or configuration.

fix

Use `import { imageMeta } from 'image-meta';` for ESM. If strictly in CommonJS, you might need specific bundler configurations or consider a `require` workaround if the package provides it, though ESM is preferred.

Upgrade

Version history

0.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/unjs/image-meta ↗

packagehttps://www.npmjs.com/package/image-meta ↗