{"id":11077,"library":"image-meta","title":"Image Meta Detector","description":"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.","status":"active","version":"0.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/image-meta","tags":["javascript","typescript"],"install":[{"cmd":"npm install image-meta","lang":"bash","label":"npm"},{"cmd":"yarn add image-meta","lang":"bash","label":"yarn"},{"cmd":"pnpm add image-meta","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { imageMeta } = require('image-meta');","symbol":"imageMeta","correct":"import { imageMeta } from 'image-meta';"},{"note":"Import the `ImageMeta` type for strong typing of the returned metadata object in TypeScript projects.","symbol":"imageMeta (type)","correct":"import type { ImageMeta } from 'image-meta';"}],"quickstart":{"code":"import { imageMeta } from 'image-meta';\n\nasync function getImageMetadata(imageUrl: string) {\n  try {\n    const response = await fetch(imageUrl);\n    if (!response.ok) {\n      throw new Error(`Failed to fetch image: ${response.statusText}`);\n    }\n    // For Node.js, you might need 'node-fetch' and res.buffer()\n    // For browser, you'd use res.arrayBuffer() and then new Uint8Array()\n    const arrayBuffer = await response.arrayBuffer();\n    const data = new Uint8Array(arrayBuffer);\n\n    const meta = imageMeta(data);\n    console.log(`Image Type: ${meta.type}`);\n    console.log(`Dimensions: ${meta.width}x${meta.height}`);\n    if (meta.orientation) {\n      console.log(`Orientation: ${meta.orientation}`);\n    }\n    return meta;\n  } catch (error) {\n    console.error('Error detecting image meta:', error);\n    throw error; // Re-throw to indicate failure\n  }\n}\n\n// Example usage with a placeholder URL\ngetImageMetadata('https://example.com/some-image.jpg')\n  .then(meta => console.log('Successfully retrieved meta:', meta))\n  .catch(err => console.error('Overall error:', err));\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Always use `try { imageMeta(data) } catch (e) { /* handle error */ }` around calls to `imageMeta`.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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())`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"When accessing `meta.orientation`, always check for its existence: `if (meta.orientation) { /* use orientation */ }`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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)`.","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.","error":"TypeError: Expected a Buffer or Uint8Array"},{"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.","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`.","error":"Error: Invalid image data or unsupported type"},{"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.","cause":"Incorrect import statement or attempting to use `imageMeta` in a CommonJS environment without proper transpilation or configuration.","error":"ReferenceError: imageMeta is not defined"}],"ecosystem":"npm"}