Configuration

Settings live in Caffeine → Settings, or in config/caffeine.php for anything that should differ per environment.

Publishing

Setting	Default	What it does
`filesystemHandle`	empty	Where artifacts are published. Empty means the local web root, which is right for most sites; naming a filesystem puts them on S3 or a CDN so PHP never serves them.
`publishPath`	`caffeine`	Directory within that filesystem or web root.
`keepVersions`	`3`	How many superseded artifacts to keep.
`precompress`	`true`	Write `.gz` and `.br` sidecars so a web server can serve them without recompressing.

keepVersions should always be more than one. A visitor who loaded the page a moment before a rebuild is still fetching the previous artifact, and pruning it out from under them turns a rebuild into a 404.

Updates

Setting	Default	What it does
`autoUpdate`	`true`	Rebuild and republish when content changes. Off means indexes only update when you say so.
`useQueue`	`true`	Build in the background rather than during the request that saved the element.
`logLevel`	`warning`	Caffeine logs to its own file under `storage/logs`.

Turning useQueue off is only sensible in tests — a synchronous build blocks the editor’s save, which is the exact cost the plugin exists to remove.

The debounce window is per index rather than global, and lives on the index definition. Thirty seconds by default; zero republishes immediately.

Per environment

// config/caffeine.php
return [
    '*' => [
        'keepVersions' => 3,
    ],
    'dev' => [
        // Rebuild synchronously so a save is visible immediately.
        'useQueue' => false,
    ],
    'production' => [
        // Publish to a CDN-backed volume instead of the web root.
        'filesystemHandle' => 'cdn',
    ],
];

Permissions

Two, both under “Caffeine” in the user group settings:

Manage indexes — see and edit index definitions.
Rebuild and republish indexes — use the buttons that queue work.

The settings screen is admin-only, because settings are project config.

Garbage collection

Caffeine hooks Craft’s garbage collection to clear derived data belonging to indexes that no longer exist. The project-config handler covers a deleted index; this covers an index whose uid changed — a restored config, a re-run seeding script — which would otherwise orphan its records and leave its artifacts being served out of the web root with nothing pointing at them.

Next: Extending