Configuration Reference

全ての設定項目は任意。

型: ImgProcUserOptions

インテグレーション設定

`imageCacheDirPattern`

画像キャッシュディレクトリ（パターン）

型: string
既定値: [cacheDir]astro-image-processor/
以下のプレースホルダーが使用可能:
- [root]: Astroの root に置換される
- [cacheDir]: Astroの cacheDir に置換される

`downloadDirPattern`

リモートファイルのダウンロードディレクトリ（パターン）

型: string
既定値: [imageCacheDir]downloads/
以下のプレースホルダーが使用可能:
- [root]: Astroの root に置換される
- [cacheDir]: Astroの cacheDir に置換される
- [imageCacheDir]: imageCacheDir の値に置換される

`imageAssetsDirPattern`

画像アセットディレクトリ（パターン）

型: string
既定値: /[assetsDirName]/
以下のプレースホルダーが使用可能:
- [assetsDirName]: Astroのアセットディレクトリに置換される（既定では _astro ）
既定の設定では画像は /_astro/[hash].[ext] に設置される

`imageOutDirPattern`

画像出力ディレクトリ（パターン）

型: string
既定値: [outDir]
以下のプレースホルダーが使用可能:
- [root]: Astroの root に置換される
- [outDir]: Astroの outDir に置換される
設定で disableCopy が true の場合、この項目の値がパスのプリフィックスとして使用される
- プレースホルダーは使用不能
- 例えば disableCopy を true に、この項目を https://cdn.example.com/assets/ に設定するとHTML出力は src="https://cdn.example.com/assets/[hash].webp" のようになる
- その上で rsync --update --delete などで imageCacheDir とCDNを同期することで各種リソースの使用を最小化できる

`imagePathBaseDirPattern`

ローカル画像の src パス解決の基準ディレクトリ

型: string
既定値: [root]
ルート相対パス（/assets/foo.png）および先頭 / なしの相対パス（assets/foo.png）に適用される。先頭 / の有無は同等に扱われる
リモートURL、data URL、/@fs/、ビルド済みアセット（/_astro/...）、ページファイル相対パス（./foo.png）、@ 始まりのパス（imagePathAliases を使用）には適用されない
以下のプレースホルダーが使用可能:
- [root]: Astroの root
- [srcDir]: Astroの srcDir
- [publicDir]: Astroの publicDir
- [outDir]: Astroの outDir
- [cacheDir]: Astroの cacheDir
[srcDir] をドキュメントルートにする例:

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

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

`imagePathAliases`

@ で始まる画像 src のパスエイリアス

型: Record<string, string>
既定値: {}
キーは @ で始める（例: @, @images）。値は imagePathBaseDirPattern と同じプレースホルダーを使うディレクトリパターン
Vite の resolve.alias や tsconfig の paths とは自動同期しない。ここで明示的に定義する
最長一致のプレフィックスが優先される（@ より @images が先）
マッチしない @ 始まりの src はエラーになる

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

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

tsconfig の "@/*": ["src/*"] に相当させる場合は '@': '[srcDir]' を設定する。

`preserveDirectories`

ディレクトリ構造を再現する

型: boolean
既定値: false
imagePathAliases または imagePathBaseDirPattern でソースファイルを解決し、srcDir からの相対パスで画像を配置する
画像ファイル名は fileNamePattern に従って解決される
imagePathBaseDirPattern: '[root]'（既定）の例
- 画像を /src/assets/images/foo/bar.png に配置し、コンポーネントの src プロパティに同じ値を設定
- 画像は /dist/assets/images/foo/[resolved fileNamePattern] に出力される
- <img> 要素等の src srcset 属性には /assets/images/foo/[resolved fileNamePattern] が出力される
imagePathBaseDirPattern: '[srcDir]' の例
- 画像を src/assets/images/foo/bar.png に配置し、src="/assets/images/foo/bar.png" を指定
出力パスはビルドを実行する Astro アプリの srcDir からの相対パスで決まる（コンポーネントの定義場所や参照元パッケージの srcDir ではない）
ソース画像がそのアプリの srcDir 配下にある場合に、既存の例どおり意図したディレクトリ構造になる
imagePathAliases などで srcDir 外（monorepo の別パッケージなど）の画像を参照する場合、出力 URL や dist 上のパスに ../ が含まれたり、想定と異なる配置になることがある。画像の読み込み・処理自体は可能だが、ディレクトリ再現の結果は保証されない
monorepo で別パッケージの画像を使う場合は、既定の preserveDirectories: false（/_astro/[hash].[ext]）の利用、または消費側アプリの srcDir 配下にアセットを置くことを検討する。エイリアス設定は imagePathAliases を参照

`fileNamePattern`

ディレクトリ構造の再現が有効な場合のファイル名出力パターン

型: string
既定値: [name]_[width]x[height]@[descriptor].[ext]?[hash8]
preserveDirectories が true の場合のみ使用される
以下のプレースホルダーが使用可能:
- [name]: 元のファイル名（拡張子を除く）
- [hash]: ファイルのハッシュ
- [hash8]: ファイルのハッシュ（先頭の8文字）
- [width]: 要素としての画像の幅
- [height]: 要素としての画像の高さ
- [descriptor]: 1x 2x 1000w 2000w
- [ext]: 拡張子
ファイル名は [name] [width] [height] [descriptor] の全てを含んでいるか、または [hash8] ないし [hash] を含んでいる必要がある
- この条件を満たさない場合、異なる画像に同じ名前が与えられる可能性がある
クエリパラメータとハッシュを利用したキャッシュバスティングが可能

`disableCopy`

キャッシュから出力ディレクトリへのコピーを無効化する

型: boolean
既定値: false
imageOutDirPattern の説明を参照

`useSrcForHash`

ローカル画像ファイルの識別用ハッシュをコンポーネントの src プロパティの文字列から取得する

型: boolean
既定値: false
ハッシュ生成時に画像ファイルを読み込む必要がないため高速
- ただし重複ファイルは検出できなくなる
ファイル名やファイルの設置ディレクトリが変わると別ファイルとして認識される点に留意する

`scopedStyleStrategy`

スコープされたスタイルの記述方法

型: "where" | "class" | "attribute"
既定値: Astroの設定を継承
参照: scopedStyleStrategy (Astro Docs)

`globalClassNames`

グローバルCSSで使用されるクラス名

型: typeof defaultGlobalClassNames
既定値: defaultGlobalClassNames
- <GlobalStyles /> コンポーネントに対応する
参照: <GlobalStyles />
変更する場合は対応するグローバルCSSを用意して設置する必要がある

`concurrency`

astro build 時の圧縮ワーカー（Piscina）の同時実行スレッド数の上限

型: number
既定値: Math.max(os.cpus().length, 1)
インテグレーションが command: 'build' で動作するときの Piscina maxThreads として使用される
dev サーバーでは devConcurrency を参照

`devConcurrency`

astro dev 時の圧縮ワーカー（Piscina）の同時実行スレッド数の上限

型: number
既定値: 3
インテグレーションが command: 'dev' で動作するときの Piscina maxThreads として使用される
値を小さくすると dev サーバーの応答性が上がりやすく、大きくするとキャッシュミス後のバックグラウンド圧縮が速くなりやすい

`devReloadOnCompressComplete`

dev で起動したバックグラウンド圧縮がすべて完了したあと、ページを full-reload するかどうか

型: boolean
既定値: false
false のときはログ出力のみ。最終画像を見るには手動でリロードする
true のとき、圧縮プールと追跡中の in-flight 作業がアイドルになった時点で Vite HMR の full-reload を 1 回送る

`devServerImageEndpoint`

dev サーバーでキャッシュディレクトリ内の圧縮画像を配信する URL パスのプレフィックス

型: string
既定値: /_aip
このパス以下へのリクエストは Vite dev サーバーの middleware 経由で imageCacheDir から配信される

`timeoutDuration`

ダウンロードタイムアウト（ミリ秒）

型: number
既定値: 50000 (5秒)
リモートファイルをダウンロードする際のタイムアウト

`retentionPeriod`

キャッシュ有効期間（ミリ秒）

型: number | null
既定値: 8640000 (100日)
設定した期間内に使用されなかった場合にキャッシュを削除対象とする
null に設定した場合、このポリシーによる削除を無効化する
retentionCount と併用する場合は AND 条件で処理される

`retentionCount`

キャッシュが直近のビルドで連続して使用されなかった場合に削除対象と判断する閾値

型: number | null
既定値: 10
「直近 n 回のビルドで連続して使用されなかったキャッシュ」を削除対象とする
- 個々のキャッシュはそれぞれカウントを保持しており、カウントはビルド時に一律で -1 される
- 使用されたキャッシュのカウントはこの項目の値にリセットされる
- ビルド完了時にカウントが0未満のキャッシュは削除される
null に設定した場合、このポリシーによる削除を無効化する
retentionPeriod と併用する場合は AND 条件で処理される

`hasher`

Bufferおよび文字列用ハッシュ生成器（関数）

型: ImgProcHasher
既定値: astro-image-processor/extras/cryptoHasher
参照: Hasher

`dataAdapter`

キャッシュデータベース用データアダプター（クラス）

型: ImgProcDataAdapter
既定値: astro-image-processor/extras/JsonFileDataAdapter
参照: Data Adapter

既定のコンポーネントプロパティ

コンポーネントのプロパティの既定値を設定する。

詳細は各コンポーネントのリファレンスを参照。

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

既定のフォーマットオプション

対応する出力フォーマットの既定のオプションを設定する。設定しない場合はsharpの初期設定が使用される。

`formatOptions.jpeg`

JPEG形式の出力オプション。

型: JpegOptions (sharp)
参照: jpeg (Output options - sharp)

`formatOptions.png`

PNG形式の出力オプション。

型: PngOptions (sharp)
参照: png (Output options - sharp)

`formatOptions.webp`

WebP形式の出力オプション。

型: WebpOptions (sharp)
参照: webp (Output options - sharp)

`formatOptions.avif`

AVIF形式の出力オプション。

型: AvifOptions (sharp)
参照: avif (Output options - sharp)

`formatOptions.gif`

GIF形式の出力オプション。

型: GifOptions (sharp)
参照: gif (Output options - sharp)