next-export-optimize-svg-images

A standalone package to optimize images for Next.js static exports, with specialized SVG support.

Features

• Static Export Friendly: Works with next export by pre-optimizing images during build.
• Multiple Formats: Generates WebP and AVIF variants.
• Responsive Breakpoints: Automatically creates resized versions based on configurable breakpoints.
• SVG Optimization: Uses SVGO for cleaning up SVGs.
• Custom React Component: <ExportImage /> automatically picks the best variant.

Installation

npm install next-export-optimize-svg-images

Usage

1. Update Scripts

Add the optimization command to your package.json:

"scripts": {
  "build": "next build",
  "postbuild": "next-export-optimize-svg-images"
}

2. Use the Component

The <ExportImage /> component now automatically picks up the manifest generated by the CLI. No manual import or provider is required by default if you use the default output folder (/optimized).

import { ExportImage } from 'next-export-optimize-svg-images';

export default function Page() {
  return (
    <ExportImage 
      src="/assets/images/hero.png" 
      alt="Hero Image"
    />
  );
}

3. Custom Manifest Path (Optional)

If you use a custom outputImageFolderName, you can let the component know where to find the manifest by setting a global variable in your root layout:

// RootLayout.tsx
if (typeof window !== 'undefined') {
  (window as any).__NEXT_EXPORT_OPTIMIZE_SVG_IMAGES_MANIFEST_PATH__ = '/custom-folder/manifest.json';
}

Alternatively, you can still use the ManifestProvider or the manifest prop if you prefer manual control:

import { ManifestProvider } from 'next-export-optimize-svg-images';
import manifest from '../public/optimized/manifest.json';

export default function App({ children }) {
  return (
    <ManifestProvider manifest={manifest}>
      {children}
    </ManifestProvider>
  );
}

Configuration

You can configure the package in three ways:

1. Dedicated Config File

Create a next-export-optimize-svg-images.config.js in your project root:

/** @type {import('next-export-optimize-svg-images').Config} */
module.exports = {
  // Array of widths to generate variants for
  breakpoints: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  
  // Images not ending in -scale will be capped at this width
  maxNonScaleBreakpoint: 1920,
  
  // Source folder for external/CMS images inside public/
  inputImageFolder: "cms-media",
  
  // Output folder name inside public/
  outputImageFolderName: "optimized",
  
  // Max images to process in parallel
  concurrency: 8,

  features: {
    avif: true,
    webp: true,
    png: false,
    svgHighRes: false, // Force high-res raster fallbacks for SVGs
  },

  // Format-specific settings (Sharp options)
  webp: { quality: 85, effort: 4, lossless: false },
  avif: { quality: 65, effort: 2, chromaSubsampling: "4:2:0" },
  png: { compressionLevel: 9, effort: 10, palette: true },
};

2. Next.js Config Integration

The tool automatically reads from next.config.js (or .mjs, .cjs). It inherits standard Next.js image settings and supports a custom imagesExport key:

// next.config.js
module.exports = {
  output: 'export',
  images: {
    deviceSizes: [640, 750, 828, 1080],
    imageSizes: [16, 32, 48, 64],
    formats: ['image/avif', 'image/webp'],
  },
  // Optional: specialized config for this tool
  imagesExport: {
    maxNonScaleBreakpoint: 2560,
    features: { svgHighRes: true }
  }
};

4. Configuration Options

• breakpoints: number[] - Array of widths to generate optimized variants for.
• maxNonScaleBreakpoint: number (default: 1920) - Images WITHOUT -scale in their filename will not be upscaled beyond this width or their original width.
• inputImageFolder: string (default: "cms-media") - The folder name inside public/ where external/CMS images are stored.
• outputImageFolderName: string (default: "optimized") - The folder name inside public/ where optimized assets will be placed.
• concurrency: number - Number of images to process in parallel (defaults to CPU count).
• features:
  • avif: boolean (default: true) - Enable AVIF generation.
  • webp: boolean (default: true) - Enable WebP generation.
  • png: boolean (default: false) - Enable PNG variant generation.
  • svgHighRes: boolean (default: false) - Force high-resolution raster fallback for SVGs.
• webp: Object with quality (0-100), effort (0-6), and lossless (boolean).
• avif: Object with quality (0-100), effort (0-9), and chromaSubsampling (e.g., "4:2:0").
• png: Object with compressionLevel (0-9), effort (1-10), and palette (boolean).

3. CLI Options

You can override the project root using --root:

next-export-optimize-svg-images --root ./my-project

SVG Support

This package has first-class support for SVG optimization and fallback:

1. SVGO Integration: Automatically cleans up SVGs.
2. Raster Fallback: Generates WebP/AVIF versions of SVGs for better performance in some contexts, but defaults to the original SVG if the raster is larger.
3. High-Res Mode: Force high-resolution raster generation for SVGs even if they exceed the original file size.

License

ISC