# How to Ignore Specific Paths from Optimization Using `ignorePaths`

> Learn how to ignore specific paths from image optimization in your Next.js project. Use ignorePaths in export-images.config.js to exclude files by their relative path.

- Repository: [d-suke/next-export-optimize-images](https://github.com/dc7290/next-export-optimize-images)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Use the `ignorePaths` array in your [`export-images.config.js`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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.

```javascript
/** 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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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.

```typescript
// 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:

```typescript
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`:

```javascript
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:

```javascript
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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/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`](https://github.com/dc7290/next-export-optimize-images/blob/main/export-images.config.js) through the `getConfig` utility in [`src/utils/getConfig.ts`](https://github.com/dc7290/next-export-optimize-images/blob/main/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.