DOCSEARCHbyAlgolia
Submit Docs

next-image-export-optimizer

repository·master·Indexed 19 days ago

https://github.com/niels-io/next-image-export-optimizer

A tool for Next.js static HTML exports that optimizes images as a post-build step. It handles resizing, WEBP conversion, and blurry placeholder generation, enabling high-performance image delivery from a CDN without requiring a Node.js server. It provides an ExportedImage component to replace next/image and supports both static and remote image optimization.

Tokens
2.1K
Snippets
8
Records
9
Agent score
19%

What's inside next-image-export-optimizer

  1. Handle Base Paths for subfolder deployment

    master

    If your application is deployed to a subfolder (e.g., example.com/subfolder), set the basePath in next.config.js. You must also pass this basePath to the ExportedImage component.

    // next.config.js
module.exports = {
  basePath: "/subfolder",
};

// Component
import ExportedImage from "next-image-export-optimizer";
import testPictureStatic from "PATH_TO_IMAGE/test_static.jpg";

<ExportedImage
  src={testPictureStatic}
  alt="Static Image"
  basePath="/subfolder"
/>

  3. Configure next-image-export-optimizer in next.config.js

    master

    To use the optimizer, you must configure next.config.js (or .ts) with a custom loader, define image sizes, and set environment variables for the optimizer's behavior. You must also transpile the package.

    Key Environment Variables:

    • nextImageExportOptimizer_imageFolderPath: The folder inside public/ where path-string images are located (default: public/images).
    • nextImageExportOptimizer_exportFolderPath: The destination for optimized images (default: out).
    • nextImageExportOptimizer_quality: Image quality (default: 75).
    • nextImageExportOptimizer_storePicturesInWEBP: Whether to convert images to WEBP (default: true).
    • nextImageExportOptimizer_generateAndUseBlurImages: Enables automatic blurry placeholder generation (default: true).
    • nextImageExportOptimizer_remoteImageCacheTTL: Cache lifetime for remote images in seconds (default: 0).
    • nextImageExportOptimizer_exportFolderName: The name of the folder within the export directory where optimized images are stored.
    // next.config.js
module.exports = {
  output: "export",
  images: {
    loader: "custom",
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
  transpilePackages: ["next-image-export-optimizer"],
  env: {
    nextImageExportOptimizer_imageFolderPath: "public/images",
    nextImageExportOptimizer_exportFolderPath: "out",
    nextImageExportOptimizer_quality: "75",
    nextImageExportOptimizer_storePicturesInWEBP: "true",
    nextImageExportOptimizer_exportFolderName: "nextImageExportOptimizer",
    nextImageExportOptimizer_generateAndUseBlurImages: "true",
    nextImageExportOptimizer_remoteImageCacheTTL: "0",
  },
};

  5. Configure and use remote images

    master

    To optimize remote images, provide a URL starting with http or https to the src prop of ExportedImage.

    Required Setup: You must create a remoteOptimizedImages.js file in your project root (next to next.config.js). This file must export an array of strings (or a Promise resolving to an array) containing all remote image URLs to be optimized at build time.

    Advanced Options:

    • Cache TTL: Control how long remote images are cached using nextImageExportOptimizer_remoteImageCacheTTL in next.config.js (e.g., 3600 for 1 hour).
    • Custom Filename: Change the name of the remote images config file using nextImageExportOptimizer_remoteImagesFilename in next.config.js.
    • Hide URLs: Use the overrideSrc prop on ExportedImage to replace the visible src attribute with a different value.
    // remoteOptimizedImages.js
module.exports = [
  "https://example.com/image1.jpg",
  "https://example.com/image2.jpg",
];

// Usage in component
import ExportedImage from "next-image-export-optimizer";

<ExportedImage src="https://example.com/remote-image.jpg" alt="Remote Image" />

  6. Disable placeholder images

    master

    To prevent the automatic generation of blurry placeholder images:

    1. Set the environment variable nextImageExportOptimizer_generateAndUseBlurImages to false in next.config.js.
    2. Set the placeholder prop of the ExportedImage component to "empty".
    <ExportedImage
  src={testPictureStatic}
  alt="No Placeholder"
  placeholder="empty"
/>

  7. Use unoptimized images

    master

    If you want to bypass the optimization process for a specific image and output the original file, use the unoptimized prop on the ExportedImage component.

    import ExportedImage from "next-image-export-optimizer";

<ExportedImage
  src={testPictureStatic}
  alt="Original, unoptimized image"
  unoptimized={true}
/>

  8. Use the ExportedImage component

    master

    Replace the standard next/image component with next-image-export-optimizer. There are two primary ways to use it:

    1. Static Import (Recommended): Import the image file directly. This allows the optimizer to know the original image dimensions.
    2. Dynamic Import (Path String): Use a string path. Note that images used this way should be placed in the folder specified by nextImageExportOptimizer_imageFolderPath (e.g., public/images).

    Note: For next/legacy/image users, import from next-image-export-optimizer/legacy/ExportedImage.

    // Recommended: Static Import
import ExportedImage from "next-image-export-optimizer";
import testPictureStatic from "PATH_TO_IMAGE/test_static.jpg";

<ExportedImage src={testPictureStatic} alt="Static Image" />

// Alternative: Dynamic Import
import ExportedImage from "next-image-export-optimizer";

<ExportedImage
  src="images/VERY_LARGE_IMAGE.jpg"
  alt="Large Image"
  width={500}
  height={500}
/>

  9. Customize export paths and config locations

    master

    You can override default paths via CLI arguments or environment variables:

    • Custom next.config.js path: Use --nextConfigPath <path> if your config is not at the root (e.g., in a monorepo).
    • Custom export folder path: Use the --exportFolderPath <path> argument or set the nextImageExportOptimizer_exportFolderPath environment variable.

    Example CLI usage:

    next build && next-image-export-optimizer --nextConfigPath path/to/my/next.config.js --exportFolderPath path/to/my/export/folder