API Reference

withOptimizedImages()

withOptimizedImages(config?: Partial<OptimizedImagesConfig>):
  (nextConfig?: NextConfig, nextComposePlugins?: NextComposePlugins) =>
    NextConfig & { webpack: Function }

Curried factory function. First call configures image optimization, second call wraps Next.js config.

// One-step
export default withOptimizedImages({ mozjpeg: { quality: 80 } })()

// Two-step
const withImages = withOptimizedImages({ optimizeImages: true })
export default withImages({ reactStrictMode: true })

Webpack Integration

The returned config includes a webpack function that:

Detects build phase (production, export, development)
Removes Next.js built-in image processing rules
Detects installed optimizer packages
Registers file/url/img loaders for each handled image format
Adds resource query handlers (?webp, ?lqip, ?sprite, etc.)
Chains with user's existing webpack function if present

OptimizedImagesConfig

interface OptimizedImagesConfig {
  optimizeImages: boolean
  optimizeImagesInDev: boolean
  handleImages: string[]
  imagesFolder: string
  imagesName: string
  imagesPublicPath?: string
  imagesOutputPath?: string
  removeOriginalExtension: boolean
  inlineImageLimit: number
  defaultImageLoader: string

  // Optimizer options
  mozjpeg: Record<string, unknown>
  optipng: Record<string, unknown>
  pngquant: Record<string, unknown>
  gifsicle: Record<string, unknown>
  svgo: Record<string, unknown>
  svgSpriteLoader: Record<string, unknown>
  webp: Record<string, unknown>
  responsive?: Record<string, unknown> & { adapter?: unknown }
  lqip?: Record<string, unknown>
  imageTrace?: Record<string, unknown>
}

Defaults

{
  optimizeImages: true,
  optimizeImagesInDev: false,
  handleImages: ['jpeg', 'png', 'svg', 'webp', 'gif'],
  imagesFolder: 'images',
  imagesName: '[name]-[hash].[ext]',
  removeOriginalExtension: false,
  inlineImageLimit: 8192,
  defaultImageLoader: 'img-loader',
  mozjpeg: {},
  optipng: {},
  pngquant: {},
  gifsicle: { interlaced: true, optimizationLevel: 3 },
  svgo: { plugins: [{ name: 'removeViewBox', active: false }] },
  svgSpriteLoader: { symbolId: '[name]-[hash:8]' },
  webp: {},
}

DetectedLoaders

interface DetectedLoaders {
  jpeg: string | false
  gif: string | false
  svg: string | false
  svgSprite: string | false
  webp: string | false
  png: string | false
  lqip: string | false
  responsive: string | false
  responsiveAdapter: string | false
}

Detection uses import.meta.resolve() for ESM-compatible module resolution. PNG prefers imagemin-optipng, falls back to imagemin-pngquant. Responsive adapter prefers sharp, falls back to jimp.

Resource Query Handlers

Each query registers a webpack rule with specific loaders:

?url

{ test: /\?url/, loaders: ['file-loader'], optimize: true }

Forces file URL output regardless of inlineImageLimit.

?inline

{ test: /\?inline/, loaders: ['url-loader'], optimize: true }

Forces data URI inlining regardless of file size.

?include

{ test: /\?include/, loaders: ['raw-loader'], optimize: true }

Returns raw file contents as a string.

?original

{ test: /\?original/, loaders: ['url-loader'], optimize: false }

Skips all optimization — returns file as-is.

?lqip

{ test: /\?lqip/, loaders: ['lqip-export-loader', 'lqip-loader', 'url-loader'], optimize: false }

Returns { src, preSrc } where preSrc is a tiny base64 placeholder.

?lqip-colors

{ test: /\?lqip-colors/, loaders: ['lqip-export-loader', 'lqip-loader', 'url-loader'], optimize: false }

Returns { palette } with extracted color data.

?trace

{ test: /\?trace/, loaders: ['image-trace-loader', 'url-loader'], optimize: true }

Returns an SVG trace outline as a data URI.

?webp

{ test: /\?webp/, loaders: ['url-loader', 'webp-loader'], optimize: true }

Converts JPEG/PNG to WebP format.

?sprite

{ test: /\?sprite/, loaders: ['svg-sprite-loader'], optimize: varies }

Generates SVG sprite symbol. If optimization is enabled, chains with img-loader.

?size=N,N,N

{ test: /\?size/, loaders: ['responsive-loader'], optimize: false }

Generates multiple image sizes for responsive <img srcset>.

Output Path Logic

Client Bundles

publicPath: `${assetPrefix}/_next/static/${imagesFolder}/`
outputPath: `static/${imagesFolder}/`

Server Bundles

outputPath: `../static/${imagesFolder}/`

The assetPrefix is read from Next.js config and prepended to public paths.

Exports

import withOptimizedImages from '@vitus-labs/tools-nextjs-images'

import type {
  DetectedLoaders,
  OptimizedImagesConfig,
} from '@vitus-labs/tools-nextjs-images'

On this page