How to Ignore Specific Paths from Optimization Using `ignorePaths`

Use the ignorePaths array in your export-images.config.js file to list paths relative to the public directory that should be copied to the output without being resized or re-encoded.

The next-export-optimize-images library processes images during Next.js static export to reduce file sizes and improve performance. However, you may need to exclude certain assets—such as raw photography or already-optimized icons—from this pipeline. By configuring the ignorePaths option in export-images.config.js, you can selectively bypass optimization for specific files or directories while still including them in the final build, as implemented in dc7290/next-export-optimize-images.

Configuring the ignorePaths Array

The library loads its configuration via the getConfig utility in src/utils/getConfig.ts, which validates the ignorePaths property as an optional array of strings. To exclude assets, create or update export-images.config.js in your project root and add the relative paths:

1. Specify paths relative to the public directory, not the project root.
2. Include directory paths to ignore entire folders, or specific file paths for granular control.
3. Re-run the export command to apply the exclusions.

/** export-images.config.js */
module.exports = {
  // Paths are relative to the `public` folder.
  ignorePaths: [
    'images/skip',          // Ignore every file under public/images/skip/
    'icons/logo.svg',       // Ignore a specific SVG file
    'assets/raw/banner.jpg' // Ignore a specific photograph
  ]
};

How the CLI Filters Ignored Paths

During execution, the CLI script in src/cli/index.ts resolves the configured relative paths to absolute file system locations. The code joins each entry with the public directory using path.join(publicDir, p) to create an array of absolute paths to exclude.

// src/cli/index.ts (excerpt)
const publicDir = path.resolve(cwd, 'public');
const ignorePaths = config.ignorePaths
  ? config.ignorePaths.map(p => path.join(publicDir, p))
  : [];

When gathering the list of images to process, the script applies a filter using !ignorePaths.includes(file) to remove any matches before optimization begins:

const publicDirImages = publicDirFiles
  .filter(file => /* image extensions */)
  .filter(file => !ignorePaths.includes(file)); // Excluded from optimization

Because this filtering occurs before any image processing, matched files are simply copied to the output directory in their original state without being touched by the optimization pipeline.

Practical Implementation Examples

Excluding Entire Directories

To skip optimization for all contents within a specific folder, provide the directory path relative to public:

module.exports = {
  ignorePaths: ['legacy-assets/']
};

This configuration preserves every file in public/legacy-assets/ exactly as-is in the final build.

Targeting Specific Files

For granular control over individual assets, list specific file paths:

module.exports = {
  ignorePaths: [
    'favicon.ico',
    'social/og-image.png',
    'downloads/press-kit.zip'
  ]
};

Verifying Your Configuration

Run the optimizer in verbose mode (the default behavior). The console outputs the complete list of collected public-folder images. If your ignorePaths configuration is correct, the specified files will be absent from this list, confirming they are being skipped during the optimization phase while still being copied to the output directory.

Summary

• The ignorePaths option in export-images.config.js controls which assets bypass the optimization pipeline.
• All paths must be specified relative to the public directory; the CLI resolves these to absolute paths at runtime.
• The filtering logic in src/cli/index.ts uses exact string matching against resolved absolute paths to exclude files.
• Ignored files are copied to the output unchanged, maintaining their original format, dimensions, and file size.
• This mechanism only affects assets located inside the public folder; files outside this directory cannot be targeted.

Frequently Asked Questions

Can I use glob patterns or wildcards in ignorePaths?

No, the current implementation in src/cli/index.ts performs exact string matches against resolved absolute paths. You must list specific directories or individual files. To ignore nested contents broadly, specify the parent directory path, which will exclude all files within that directory from optimization.

Does ignorePaths prevent files from being copied to the build output?

No, files listed in ignorePaths are still copied to the final build directory during the export process. The filter only prevents them from being processed, resized, or re-encoded by the optimization pipeline. They appear in the output exactly as they exist in the source public folder.

Where does the library load the ignorePaths configuration?

The configuration is loaded from export-images.config.js through the getConfig utility in src/utils/getConfig.ts, which validates the configuration object and passes it to the CLI. Ensure your config file is located in the project root and exports an object containing the ignorePaths array.

Can I ignore paths outside the public directory?

No, the ignorePaths mechanism specifically targets the public folder. The CLI resolves all configured paths relative to public using path.join(publicDir, p), so attempting to reference files outside this directory will not work as intended. For assets located elsewhere, use Next.js's built-in static file handling or adjust your build configuration accordingly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}