Next-universal-image-optimizer NPM

next-universal-image-optimizer

A build-time image optimization tool for Next.js (and other static build environments) that supports both internal and external images. It allows you to:

Fetch images from remote URLs (e.g., from a CMS).
Discover and optimize local images via glob patterns (e.g., public/images/**/*).
Generate multiple responsive variants in various widths or scales.
Convert images to optimized formats (e.g., WebP) with configurable quality.

Note: This tool is designed for static builds and works well with next export scenarios, where dynamic optimization provided by next/image is not available.

Features

Universal Input: Supports both local files and remote URLs.
Configurable: Easily adjust widths, quality, output directories, and modes (widths/scales) via config or runtime options.
Uses Sharp: sharp handles efficient resizing and conversion.
Next.js Integration: Ideal for next export scenarios to ensure that final static output images are optimized.

Installation

Use your package manager of choice:

pnpm add next-universal-image-optimizer

(You can also use npm or yarn.)

Usage

1. Configuration File

Create nuio.config.ts (or .js) at your project root:

export default {
   inputPaths: [
      // 'https://example.com/remote-image.jpg',
      // 'public/images/local-file.png'
   ],
   outputPatterns: [
      'public/images/**/*.{jpg,png,webp}'
   ],
   outputDir: 'out/images',
   widths: [640, 1280, 1920],
   quality: 80,
   modes: ['scales', 'widths'], // enable scaling and widths mode
   scales: {
      '@3x': 1,
      '@2x': 2/3,
      '@1x': 1/3
   },
   envMode: process.env.ENV_MODE || 'development'
}

2. Calling `optimizeImages`

Call optimizeImages() without arguments to use nuio.config.ts defaults:

import { optimizeImages } from 'next-universal-image-optimizer'

async function run() {
  await optimizeImages()
  console.log('Images optimized successfully!')
}

run().catch(err => {
  console.error('Failed to optimize images:', err)
  process.exit(1)
})

You can override defaults by passing options:

await optimizeImages({
  inputPaths: ['https://example.com/another-remote.jpg'],
  outputPatterns: ['public/images/**/*.png'],
  widths: [320, 640],
  quality: 90
})

3. Integrating with Next.js (`next export`)

For next export scenarios, run optimizeImages after exporting:

Example package.json scripts:

{
   "scripts": {
      "prebuild": "node scripts/fetch-images.js",
      "build": "next build && next export && node scripts/post-export-optimize.js"
   }
}

In scripts/post-export-optimize.js:

import { optimizeImages } from 'next-universal-image-optimizer'

async function postExport() {
   await optimizeImages()
   console.log('Images optimized successfully!')
}

postExport().catch(console.error)

After next export, optimized images will be in out/images. Reference them directly in your static HTML.

4. Testing

Use Jest or another test runner. For examples, see test/index.test.ts for mock and snapshot testing patterns.

5. Advanced Usage

External Image Lists: Fetch a list of remote images from a CMS and pass them to optimizeImages before building.
Different Formats: By default, images are converted to WebP. Adjust sharp options to convert to other formats if needed.