{"id":13604,"library":"next-export-optimize-images","title":"Build-time Image Optimization for Next.js Exports","description":"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.","status":"active","version":"4.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/dc7290/next-export-optimize-images","tags":["javascript","next.js","static","export","image","optimization","typescript"],"install":[{"cmd":"npm install next-export-optimize-images","lang":"bash","label":"npm"},{"cmd":"yarn add next-export-optimize-images","lang":"bash","label":"yarn"},{"cmd":"pnpm add next-export-optimize-images","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Next.js applications, specifically for static export feature.","package":"next","optional":false},{"reason":"Required peer dependency for Next.js and React components.","package":"react","optional":false},{"reason":"Required peer dependency for Next.js and React components.","package":"react-dom","optional":false}],"imports":[{"note":"Used in `next.config.mjs` to wrap your Next.js configuration. ESM format is recommended for `next.config.mjs`.","wrong":"const withExportImages = require('next-export-optimize-images')","symbol":"withExportImages","correct":"import { withExportImages } from 'next-export-optimize-images'"},{"note":"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.","wrong":"import { ExportedImage } from 'next-export-optimize-images'","symbol":"RemoteImage","correct":"import { RemoteImage } from 'next-export-optimize-images'"},{"note":"TypeScript type for extending the plugin's configuration options in `next.config.mjs`.","symbol":"Config (type)","correct":"import type { Config } from 'next-export-optimize-images'"}],"quickstart":{"code":"// next.config.mjs\nimport { withExportImages } from 'next-export-optimize-images';\n\nconst nextConfig = {\n  output: 'export', // Essential for static export\n  images: {\n    // Strongly recommended to set to true to prevent conflicts with Next.js's built-in loader\n    unoptimized: true,\n  },\n  // Optional: Plugin-specific configuration\n  exportOptimizeImages: {\n    quality: 75,\n    formats: ['webp', 'jpeg'],\n  },\n};\n\nexport default withExportImages(nextConfig);\n\n// pages/index.tsx (or app/page.tsx)\nimport Image from 'next/image';\n\nexport default function HomePage() {\n  return (\n    <div>\n      <h1>Optimized Image Example</h1>\n      {/* Place a local image in your `public` directory, e.g., `public/my-image.jpg` */}\n      <Image\n        src=\"/my-image.jpg\"\n        alt=\"A local image optimized at build time\"\n        width={600}\n        height={400}\n        priority // Ensures it's optimized early\n      />\n      <p>Run `npm run build && npm run export` to generate optimized images in your static output.</p>\n    </div>\n  );\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure `output: 'export'` is present in your `next.config.mjs`.","message":"The `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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js environment to version 18 or later.","message":"Node.js version 18 or higher is required. Using older Node.js versions will lead to build failures.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Add `images: { unoptimized: true }` to your `next.config.mjs`.","message":"It 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.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"For remote images, consider using the provided `RemoteImage` component or declare remote URLs in `remoteOptimizedImages.js` as per documentation.","message":"When 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.","severity":"gotcha","affected_versions":">=4.4.0"}],"env_vars":null,"search_vec":"'abil':111 'activ':70 'ad':89 'app':140 'applic':19 'avail':51 'benefit':41 'bring':39 'bug':82 'build':2,26 'build-tim':1 'built':46 'built-in':45 'cach':128 'cadenc':72 'chunk':90 'compat':85 'comprehens':144 'convert':113 'current':65 'deploy':58 'design':20 'differenti':100 'download':121 'e.g':116 'environ':59 'export':8,11,33,62,155 'extern':123 'fast':107 'featur':81 'fix':83 'focus':78 'format':115 'fulli':135 'generat':35 'high':148 'high-perform':147 'imag':4,13,23,48,92,108,114,124,156 'improv':86 'includ':101 'javascript':152 'key':99 'librari':64 'local':120 'maintain':68 'mechan':129 'new':80 'next':10,32 'next-export-optimize-imag':9 'next.js':7,18,43,139,153 'node.js':97 'optim':5,12,22,49,133,157 'per':76 'perform':149 'png':117 'prevent':131 'process':27,93,109 'project':30 'provid':142 'redund':132 'releas':71 'render':56 'robust':127 'router':141 'server':55 'server-rend':54 'sever':74 'sharp':105 'site':37 'solut':145 'specif':28 'static':36,61,150,154 'support':95,136 'time':3 'typescript':137,158 'typic':50 'updat':75 'use':103 'util':16,31 'v22':98 'v4.7.0':67 'webp':119 'websit':151 'year':77","created_at":"2026-04-20T01:55:22.047401+00:00","updated_at":"2026-04-20T01:55:22.047401+00:00","problems":[{"fix":"Set `output: 'export'` and `images: { unoptimized: true }` in your `next.config.mjs`.","cause":"Missing or incorrect `output: 'export'` or `images.unoptimized: true` in `next.config.js`.","error":"Error: Image Optimization using the default loader is not compatible with `{ output: 'export' }`."},{"fix":"Verify the image path is correct relative to your `public` directory or the location of statically imported images. Check `public` folder for images.","cause":"The image file specified in `src` does not exist at the given path, or there's a misconfiguration in image sourcing.","error":"Error: ENOENT: no such file or directory, stat '/path/to/image.jpg'"},{"fix":"Update your Node.js environment to version 18 or higher.","cause":"The project's Node.js version is below the minimum requirement of 18.","error":"Build failed due to incompatible Node.js version."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"next-export-optimize-images","cli_version":null,"type":"library","homepage":"https://next-export-optimize-images.vercel.app","github":"https://github.com/dc7290/next-export-optimize-images","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/next-export-optimize-images","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","devops","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}