Configuration Reference

All configurations are optional.

Type: ImgProcUserOptions

Integration Settings

`imageCacheDirPattern`

Image cache directory pattern.

Type: string
Default: [cacheDir]astro-image-processor/
The following placeholders can be used:
- [root]: Replaced with Astro’s root
- [cacheDir]: Replaced with Astro’s cacheDir

`downloadDirPattern`

Directory for downloading remote files pattern.

Type: string
Default: [imageCacheDir]downloads/
The following placeholders can be used:
- [root]: Replaced with Astro’s root
- [cacheDir]: Replaced with Astro’s cacheDir
- [imageCacheDir]: Replaced with the value of imageCacheDir

`imageAssetsDirPattern`

Image assets directory pattern.

Type: string
Default: /[assetsDirName]/
The following placeholders can be used:
- [assetsDirName]: Replaced with Astro’s asset directory (default is _astro)
By default, images will be placed at /_astro/[hash].[ext].

`imageOutDirPattern`

Image output directory pattern.

Type: string
Default: [outDir]
The following placeholders can be used:
- [root]: Replaced with Astro’s root
- [outDir]: Replaced with Astro’s outDir
If disableCopy is set to true, the value of this item is used as a prefix for the path:
- Placeholder is disabled.
- For example, if disableCopy is true and this item is set to https://cdn.example.com/assets/, the HTML output will be like src="https://cdn.example.com/assets/[hash].webp".
- Additionally, you can minimize resource usage by synchronizing imageCacheDir with the CDN using rsync --update --delete, etc.

`imagePathBaseDirPattern`

Base directory for resolving local image src paths.

Type: string
Default: [root]
Applies to root-relative paths (/assets/foo.png) and bare relative paths (assets/foo.png). A leading / is optional.
Does not apply to remote URLs, data URLs, /@fs/, built assets (/_astro/...), page-relative paths (./foo.png), or @-prefixed paths (use imagePathAliases).
The following placeholders can be used:
- [root]: Replaced with Astro’s root
- [srcDir]: Replaced with Astro’s srcDir
- [publicDir]: Replaced with Astro’s publicDir
- [outDir]: Replaced with Astro’s outDir
- [cacheDir]: Replaced with Astro’s cacheDir
Example with [srcDir] as the document root:

astroImageProcessor({
    imagePathBaseDirPattern: '[srcDir]',
});

<Image src="/assets/images/foo.png" alt="..." width={800} height={600} />

`imagePathAliases`

Path aliases for image src values starting with @.

Type: Record<string, string>
Default: {}
Keys must start with @ (e.g. @, @images). Values are directory patterns with the same placeholders as imagePathBaseDirPattern.
Not synced from Vite resolve.alias or tsconfig paths; define explicitly here.
Longest matching prefix wins (@images before @).
Unknown @-prefixed src values throw an error.

astroImageProcessor({
    imagePathAliases: {
        '@': '[srcDir]',
        '@images': '[srcDir]/assets/images',
    },
});

<Image src="@/assets/foo.png" alt="..." width={800} height={600} />

To mirror tsconfig "@/*": ["src/*"], set '@': '[srcDir]'.

`preserveDirectories`

Preserve directory structure for image files.

Type: boolean
Default: false
Place images by paths relative to srcDir, using resolveSourceFilePath (imagePathAliases or imagePathBaseDirPattern) to locate the source file on disk.
Image filenames are resolved according to fileNamePattern.
Example with default imagePathBaseDirPattern: '[root]':
- Place the source file in /src/assets/images/foo/bar.png and set the src property in the component to the same value.
- Image output to /dist/assets/images/foo/[resolved fileNamePattern].
- The src and srcset of the <img> element will contain /assets/images/foo/[resolved fileNamePattern].
Example with imagePathBaseDirPattern: '[srcDir]':
- Place the source file at src/assets/images/foo/bar.png and set src="/assets/images/foo/bar.png".
Output paths are computed relative to the consuming Astro app’s srcDir, not relative to the component file or source package.
Works as intended when source images live under that app’s srcDir (the existing examples assume this).
When imagePathAliases resolves images outside the app’s srcDir (e.g. monorepo shared packages), output URLs and dist layout may include ../ segments or otherwise differ from in-app assets. File processing still works; only directory preservation may not match expectations.
For cross-package images in a monorepo, prefer leaving preserveDirectories at false (default /_astro/[hash].[ext] output), or keep assets under the consuming app’s srcDir. See also imagePathAliases.

`fileNamePattern`

File name pattern when the preserve directory structure option is enabled.

Type: string
Default: [name]_[width]x[height]@[descriptor].[ext]?[hash8]
Supports the following placeholders:
- [name]: Original file name (without extension)
- [hash]: File hash (full)
- [hash8]: File hash (first 8 characters)
- [width]: Resolved width
- [height]: Resolved height
- [descriptor]: 1x, 2x, 1000w, 2000w
- [ext]: Extension
The file name must include all of [name], [width], [height], and [descriptor], or include [hash8] or [hash].
- If this condition is not met, different images may be given the same name.
A cache buster can be specified using the hash and query parameter.

`disableCopy`

Disable copying from the cache to the output directory.

Type: boolean
Default: false
Refer to the description of imageOutDirPattern.

`useSrcForHash`

Use the string from the component’s src property to generate a hash for identifying local image files.

Type: boolean
Default: false
Faster since it doesn’t require reading the image file during hash generation.
- However, duplicate files cannot be detected.
Note that files will be recognized as different if the file name or directory changes.

`scopedStyleStrategy`

Specify the strategy used for scoping styles.

Type: "where" | "class" | "attribute"
Default: Inherits Astro’s settings.
Reference: scopedStyleStrategy (Astro Docs)

`globalClassNames`

Class names used in global CSS.

Type: typeof defaultGlobalClassNames
Default: defaultGlobalClassNames
- Corresponds to the <GlobalStyles /> component.
Reference: <GlobalStyles />
If changed, need to create and place the corresponding global CSS.

`concurrency`

Maximum number of concurrent compression worker threads during astro build.

Type: number
Default: Math.max(os.cpus().length, 1)
Used as Piscina maxThreads when the integration runs with command: 'build'.
For the dev server, see devConcurrency.

`devConcurrency`

Maximum number of concurrent compression worker threads during astro dev.

Type: number
Default: 3
Used as Piscina maxThreads when the integration runs with command: 'dev'.
Lower values can improve dev server responsiveness; higher values can speed up background variant generation after a cache miss.

`devReloadOnCompressComplete`

Whether to trigger a full page reload after all background compression jobs started in the current dev session have finished.

Type: boolean
Default: false
When false, completion is logged only; reload the page manually to see final optimized images.
When true, uses Vite HMR full-reload once after the compression pool and tracked in-flight work are idle.

`devServerImageEndpoint`

URL path prefix for serving compressed images from the cache directory in the dev server.

Type: string
Default: /_aip
Requests under this path are served from imageCacheDir via a Vite dev-server middleware.

`timeoutDuration`

Download timeout duration in milliseconds.

Type: number
Default: 50000 (5 seconds)
Timeout duration for downloading remote files.

`retentionPeriod`

Cache retention period in milliseconds.

Type: number | null
Default: 8640000 (100 days)
If not used within the set period, the cache will be subject to deletion.
If set to null, deletion by this policy is disabled.
If both retentionPeriod and retentionCount are enabled, they are processed under AND conditions.

`retentionCount`

Threshold to determine if the cache should be deleted if not used consecutively in the recent builds.

Type: number | null
Default: 10
Caches that have not been used consecutively in the last n builds will be subject to deletion:
- Each cache keeps its own count, which is decremented by -1 uniformly during build.
- The count of used caches is reset to the value of this item.
- Caches with a count less than 0 at the end of the build are deleted.
If set to null, deletion by this policy is disabled.
If both retentionPeriod and retentionCount are enabled, they are processed under AND conditions.

`hasher`

Hash generator for Buffer and strings (function).

Type: ImgProcHasher
Default: astro-image-processor/extras/cryptoHasher
Reference: Hasher

`dataAdapter`

Data adapter for cache database (class).

Type: ImgProcDataAdapter
Default: astro-image-processor/extras/JsonFileDataAdapter
Reference: Data Adapter

Default Component Properties

Set the default values for the component properties.

See each component reference for details.

componentProps.placeholder
componentProps.placeholderColor
componentProps.devPlaceholder
componentProps.blurProcessor
componentProps.upscale
componentProps.layout
componentProps.objectFit
componentProps.objectPosition
componentProps.enforceAspectRatio
componentProps.backgroundSize
componentProps.backgroundPosition
componentProps.preload
componentProps.format
componentProps.formats
componentProps.tagName
componentProps.crossOrigin
componentProps.minAge
componentProps.maxAge

Default Format Options

Set the default options for the corresponding output formats. If not set, the default settings of sharp will be used.

`formatOptions.jpeg`

Output options for JPEG format.

Type: JpegOptions (sharp)
Reference: jpeg (Output options - sharp)

`formatOptions.png`

Output options for PNG format.

Type: PngOptions (sharp)
Reference: png (Output options - sharp)

`formatOptions.webp`

Output options for WebP format.

Type: WebpOptions (sharp)
Reference: webp (Output options - sharp)

`formatOptions.avif`

Output options for AVIF format.

Type: AvifOptions (sharp)
Reference: avif (Output options - sharp)

`formatOptions.gif`

Output options for GIF format.

Type: GifOptions (sharp)
Reference: gif (Output options - sharp)