directus-extension-generate-image-previews

Pre-generate Directus image transform ("preview") cache files so the admin UI and API never pay the first-request sharp cost.

A Directus bundle:

• upload hook — warm previews right after an image upload.
• new-preset trigger — Run now warms every preset (system + custom) for existing images.
• backfill job — resumable, window-aware sweep over the existing library.
• admin module — progress, storage breakdown, configuration, diagnostics, and API reference.

Target: self-hosted Directus 11.17.4 (PM2 cluster, local disk storage).

Why this approach (read AGENTS.md too)

The cache file is <filename_disk>__<object-hash(resolved transforms)>.<ext>. The hash depends on the RESOLVED transforms, and every system-* preset is format:'auto' — which resolves differently server-side (jpg/png) than in a browser (avif). We therefore generate in-process with an explicit acceptFormat (avif + webp), reproducing the browser's cache file byte-for-byte without any HTTP request. Naive warming (or the popular community extension) silently misses.

Install / build / publish

npm install
npm run build        # emits dist/app.js + dist/api.js
npm run typecheck    # 0 errors
npm test             # unit tests
npm run dev          # watch build
npm run publish      # scp dist + package.json to the (staging) deploy target

Settings

Defaults are applied automatically; everything is editable at runtime from the admin module — no rebuild.

setting	default	meaning
enabled	true	master switch (off = hooks/backfill inert)
onUpload	true	generate previews immediately after an upload
windowStart / windowEnd	01:00 / 04:00	scheduled runs only start inside this window (local time)
concurrency	1	parallel generations
formats	avif,webp	output variants for format:'auto' presets only (all system presets)
presetKeys	null (all)	restrict to specific preset keys
debug	false	verbose generation logs in the Directus server log
IMAGE_PREVIEWS_STATE_DIR	<STORAGE_LOCAL_ROOT>/.image-previews	where settings + progress state live

Presets and formats

• System presets (system-small|medium|large × cover|contain) always use format:'auto', so they generate one file per entry in formats (default avif + webp), at their built-in sizes (64 / 300 / 800 px).
• Custom presets from Settings → File Storage are added automatically. A custom preset with a fixed format (e.g. png) ignores formats and generates exactly that format. A custom preset with format:'auto' follows formats.
• A custom preset whose key equals a system key is shadowed (system wins, same as Directus) and is flagged in the admin module.

Storage reporting

GET /image-previews/disk-usage (and the admin panel) reports bytes + file counts separately for preview assets and original assets, plus the total — in both raw bytes and human-readable form.

API endpoints

All require an admin session or admin token. Human-readable fields accompany machine-readable ones.

• GET /image-previews/status — run progress, rate, ETA, window state, ISO + human dates
• GET /image-previews/config, PUT /image-previews/config
• GET /image-previews/presets — system + custom presets, effective formats, shadowed keys
• POST /image-previews/run — start backfill ({"ignoreWindow":true} for an immediate run)
• POST /image-previews/run/cancel
• GET /image-previews/disk-usage — previews vs originals vs total
• POST /image-previews/generate — one file ({fileId, keys?, formats?, dryRun?})
• GET /image-previews/resolve-plan?fileId=&key= — predicted cache filename, no write
• GET /image-previews/ops?limit= — recent operations with timing + error messages

The admin module includes a full API reference with curl examples.

Safe testing & deployment

Never test against the prod instance.

• Local / staging (dev/compose.dev.yml): Directus 11.17.4 + its own postgres + volumes, on separate ports. Shares nothing with prod. See dev/README.md.
• Fail-open: entrypoints never throw into Directus core.
• Rollout: build → verify on staging → back up previous dist/ → deploy → healthcheck → enable. Rollback: restore previous dist/.
• Scripts: dev/deploy-staging.sh, dev/rollback-staging.sh, template dev/compose.staging.yml.

Caveats

• Transform dimension guard, not a file-size limit. Directus rejects transformations of images whose width or height exceeds ASSETS_TRANSFORM_IMAGE_MAX_DIMENSION (default 6000 px). This is a Directus env var, not something this extension imposes. To process larger images, raise it on the Directus instance (and watch memory). Upload size limits (FILES_MAX_UPLOAD_SIZE, MAX_PAYLOAD_SIZE) are separate.
• Warm only after uploads are committed (local writes are non-atomic).
• In-process generation bypasses the HTTP rate limiter; bound it with concurrency + the window.
• Unsupported custom preset formats (e.g. bmp) fail at generation time; the error appears in Recent operations / /ops.

See .opencode/goal.md for the full contract and .opencode/feature_list.json for the task list.