@randajan/esbuild-plugin-image-size NPM

@randajan/esbuild-plugin-image-size

🚀 Features

✅ Extracts image metadata (width, height, aspectRatio)
✅ Generates an importable object when using images in ESBuild
✅ Supports file filtering using entries (like .gitignore)
✅ Works on all platforms (Windows, Linux, macOS)
✅ Optimized for performance – filters files directly in onLoad

📦 Installation

npm install esbuild-plugin-image-meta --save-dev

📌 Usage

🖼 Importing an image

import image from "./assets/photo.jpg";

console.log(image);
/*
{
  src: "/images/photo.jpg",
  width: 1920,
  height: 1080,
  aspectRatio: 1.777
}
*/

🔧 Configuration

You can configure the plugin with the following options:

import esbuild from "esbuild";
import imageSizePlugin from "esbuild-plugin-image-meta";

esbuild.build({
    entryPoints: ["src/index.js"],
    bundle: true,
    outdir: "dist",
    plugins: [
        imageSizePlugin({
            entries: ["src/images/**", "!src/excluded/**"], // Filter files
            extensions: ["png", "jpg"],                    // Allowed image types
            outputDir: "assets",                           // Output directory
            trait: (meta, buffer) => ({                    // Modify metadata (optional)
                ...meta,
                size: buffer.byteLength
            })
        })
    ]
}).catch(() => process.exit(1));

🎯 Options

Option	Type	Default	Description
`entries`	`string \| string[]`	`"*"` (process all)	Defines which images should be processed (supports glob patterns).
`extensions`	`string[]`	`["png", "jpg", "jpeg", "gif", "webp", "svg"]`	Specifies which image types to process.
`outputDir`	`string`	`"images"`	Defines where processed images are stored in the output directory.
`trait`	`(meta, buffer) => object`	Identity function	Allows modifying the export object before bundling.

📌 Example with Custom Metadata

If you want to add the file size to the exported object:

imageSizePlugin({
    trait: (meta, buffer) => ({
        ...meta,
        size: buffer.byteLength
    })
});

Would generate:

{
  src: "/images/photo.jpg",
  width: 1920,
  height: 1080,
  aspectRatio: 1.777,
  size: 345678
}

📄 License

🔥 Now your ESBuild pipeline automatically processes images and gives you structured metadata! 🚀

fetch json http api network request rest ajax wrapper error-handling

image-size micromatch

1.0.2

8 months ago

1.0.1

8 months ago