Registry / web-framework / next-export-optimize-images

next-export-optimize-images

library4.7.0jsnpmunverified

next-export-optimize-images is a utility for Next.js applications designed to optimize images during the build process, specifically for projects utilizing `next export` to generate static sites. It brings the benefits of Next.js's built-in image optimization, typically available only in server-rendered or deployed environments, to static exports. The library, currently at v4.7.0, maintains an active release cadence with several updates per year, focusing on new features, bug fixes, and compatibility improvements, such as adding chunking for image processing and support for Node.js v22. Key differentiators include its use of `sharp` for fast image processing, the ability to convert image formats (e.g., PNG to WebP), local downloading of external images, and a robust caching mechanism to prevent redundant optimizations. It fully supports TypeScript and Next.js App Router, providing a comprehensive solution for high-performance static websites.

web-framework devops data

npm install next-export-optimize-images

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEXT-EXPORT-OPTIMI

next-export-optimize-images

web-frameworkjavascriptv4.7.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

withExportImages

✓ import { withExportImages } from 'next-export-optimize-images'

✗ const withExportImages = require('next-export-optimize-images')

Used in `next.config.mjs` to wrap your Next.js configuration. ESM format is recommended for `next.config.mjs`.

RemoteImage

✓ import { RemoteImage } from 'next-export-optimize-images'

✗ import { ExportedImage } from 'next-export-optimize-images'

Use this component to optimize remote images during the build process. The `ExportedImage` component from `next-image-export-optimizer` (a similar but distinct library) is a common confusion point.

Config (type)

✓ import type { Config } from 'next-export-optimize-images'

TypeScript type for extending the plugin's configuration options in `next.config.mjs`.

Demonstrates how to configure `next-export-optimize-images` in `next.config.mjs` and use `next/image` for local assets for build-time optimization in a Next.js static export.

// next.config.mjs import { withExportImages } from 'next-export-optimize-images'; const nextConfig = { output: 'export', // Essential for static export images: { // Strongly recommended to set to true to prevent conflicts with Next.js's built-in loader unoptimized: true, }, // Optional: Plugin-specific configuration exportOptimizeImages: { quality: 75, formats: ['webp', 'jpeg'], }, }; export default withExportImages(nextConfig); // pages/index.tsx (or app/page.tsx) import Image from 'next/image'; export default function HomePage() { return ( <div> <h1>Optimized Image Example</h1> {/* Place a local image in your `public` directory, e.g., `public/my-image.jpg` */} <Image src="/my-image.jpg" alt="A local image optimized at build time" width={600} height={400} priority // Ensures it's optimized early /> <p>Run `npm run build && npm run export` to generate optimized images in your static output.</p> </div> ); }

next-export-optimize-images --version

Debug

Known issues

breakingThe `output: 'export'` option must be explicitly set in `next.config.mjs`. This plugin is designed for Next.js static exports and will not function correctly without this configuration. Next.js's default image optimization relies on a server, which is absent in static exports.

fix

Ensure `output: 'export'` is present in your `next.config.mjs`.

affects: >=4.0.0

breakingNode.js version 18 or higher is required. Using older Node.js versions will lead to build failures.

fix

Upgrade your Node.js environment to version 18 or later.

affects: >=4.0.0

gotchaIt is highly recommended to set `images.unoptimized: true` in your `next.config.mjs` when using this plugin. This prevents potential conflicts with Next.js's default image loader, which is incompatible with static exports.

fix

Add `images: { unoptimized: true }` to your `next.config.mjs`.

affects: >=4.0.0

gotchaWhen optimizing remote images, you often need to define them in a `remoteOptimizedImages.js` file or use the `RemoteImage` component. Simply adding remote URLs to `next/image` might not trigger optimization or could lead to build errors if not configured correctly.

fix

For remote images, consider using the provided `RemoteImage` component or declare remote URLs in `remoteOptimizedImages.js` as per documentation.

affects: >=4.4.0

Errors

Common errors & fixes

Error: Image Optimization using the default loader is not compatible with `{ output: 'export' }`.

Missing or incorrect `output: 'export'` or `images.unoptimized: true` in `next.config.js`.

fix

Set `output: 'export'` and `images: { unoptimized: true }` in your `next.config.mjs`.

Error: ENOENT: no such file or directory, stat '/path/to/image.jpg'

The image file specified in `src` does not exist at the given path, or there's a misconfiguration in image sourcing.

fix

Verify the image path is correct relative to your `public` directory or the location of statically imported images. Check `public` folder for images.

Build failed due to incompatible Node.js version.

The project's Node.js version is below the minimum requirement of 18.

fix

Update your Node.js environment to version 18 or higher.

Upgrade

Version history

4.7.0latest on npm

Audit

Dependencies

nextrequiredRequired peer dependency for Next.js applications, specifically for static export feature.

reactrequiredRequired peer dependency for Next.js and React components.

react-domrequiredRequired peer dependency for Next.js and React components.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/dc7290/next-export-optimize-images ↗

packagehttps://www.npmjs.com/package/next-export-optimize-images ↗

homepagehttps://next-export-optimize-images.vercel.app ↗