Image Meta Detector

0.2.2 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: Expected a Buffer or Uint8Array
```
cause 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
```
cause 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
```
cause 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.

Warnings

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`.
gotcha The 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())`.
gotcha The `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 */ }`.

Install

npm install image-meta npm
yarn add image-meta yarn
pnpm add image-meta pnpm

Imports

imageMeta
wrong:
```
const { imageMeta } = require('image-meta');
```
correct:
```
import { imageMeta } from '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.

Quickstart

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));

view raw JSON →