rollup-plugin-napi-image

0.6.1 verified Mon Apr 27 auth: no javascript

Rollup and Vite plugin for optimizing images (JPEG, PNG, WebP, AVIF) using napi-rs/Image, a native Rust-based image processing library. Version 0.6.1 released in 2025. It supports both lossy (with configurable quality) and lossless modes, and allows conversion to modern formats (e.g., WebP to AVIF) via a custom function. Unlike imagemin-based plugins, it avoids node-gyp and provides faster performance via N-API. Compatible with Rollup and Vite, with TypeScript types included. Good for build-time image optimization in modern bundler setups.

Common errors

error Error: Cannot find module 'rollup-plugin-napi-image' ↓

cause Package not installed or not in node_modules.

fix

Run: npm install rollup-plugin-napi-image --save-dev

error TypeError: napiImage is not a function ↓

cause Default import used instead of named import.

fix

Use: import { napiImage } from 'rollup-plugin-napi-image'

error Error: Unsupported image format: .svg ↓

cause Input file has an unsupported extension.

fix

Remove SVG files from the rollup pipeline or set include to only supported extensions.

error Plugin napiImage: The 'mode' option is required. ↓

cause Missing mode in options.

fix

Add mode: 'lossy' or 'lossless' to plugin options.

error Error: [plugin: napiImage] Could not optimize image. (code: ENOTDIR) ↓

cause The input path for an image is a directory instead of a file.

fix

Ensure include patterns match only files, not directories.

Warnings

deprecated Option format may change in future versions (e.g., include/exclude patterns). ↓

fix Pin version if stable: "rollup-plugin-napi-image": "0.6.1"

gotcha The plugin only runs during bundle build; it does not optimize images in watch mode or dev server by default. ↓

fix Ensure production build runs image optimization separately or use manual rebuild.

gotcha toModernExt function must return one of the supported extensions: 'jpg' | 'jpeg' | 'png' | 'webp' | 'avif'. Invalid return may cause build errors. ↓

fix Restrict return type to supported extensions.

breaking Previously named export was 'napiImagePlugin' in v0.5.x; renamed to 'napiImage' in v0.6.0. ↓

fix Update import to { napiImage } from 'rollup-plugin-napi-image'

gotcha WARNING: The plugin requires Node.js >= 16 because of napi-rs dependencies. ↓

fix Upgrade Node.js to version 16 or higher, or use an older version of the plugin that supports Node 14.

deprecated The 'quality' option is currently only effective for lossy mode; setting it in lossless mode has no effect. ↓

fix Only set quality when mode is 'lossy'.

gotcha Unsupported file types (e.g., SVG, GIF) are silently ignored; no error is thrown. ↓

fix Use include/exclude patterns to filter out unsupported types.

Install

npm install rollup-plugin-napi-image

yarn add rollup-plugin-napi-image

pnpm add rollup-plugin-napi-image

Imports

napiImage

wrong

import napiImage from 'rollup-plugin-napi-image'

correct

import { napiImage } from 'rollup-plugin-napi-image'

Named export; default import does not exist.

napiImage

wrong

const napiImage = require('rollup-plugin-napi-image')

correct

const { napiImage } = require('rollup-plugin-napi-image')

CommonJS require must destructure the named export.

Mode
```
import { Mode } from 'rollup-plugin-napi-image'
```
TypeScript type for mode option: 'lossy' | 'lossless'. Importing the type is optional but useful for typed config.

Quickstart

Rollup config with napiImage plugin: lossy compression at quality 75, excluding sprite.png, and converting WebP to AVIF.

// rollup.config.js
import { defineConfig } from 'rollup';
import { napiImage } from 'rollup-plugin-napi-image';

export default defineConfig({
  input: 'src/index.js',
  output: { dir: 'dist', format: 'esm' },
  plugins: [
    napiImage({
      mode: 'lossy',
      quality: 75,
      include: ['**/*.{jpg,jpeg,png,webp,avif}'],
      exclude: ['**/sprite.png'],
      toModernExt: (ext) => ext === 'webp' ? 'avif' : ext,
    }),
  ],
});