Delivery

Last updated: August 19th 2026

Super Images mirrors Craft’s generateTransformsBeforePageLoad.

generateBeforePageLoad
'delivery' => [
    // true  = generate missing files during Twig, emit storage/CDN URLs
    // false = emit signed action URL when missing (browser hits runtime endpoint)
    // omit  = use Craft::$app->config->general->generateTransformsBeforePageLoad
    'generateBeforePageLoad' => true,
],
SettingMissing fileURL in HTML
trueGenerated during the page requestStorage/CDN URL
falseGenerated when the browser hits the action/actions/super-images/runtime/generate?...

If the file already exists, Twig always emits the storage URL.

Runtime endpoint (only when generateBeforePageLoad is false)

'runtime' => [
    'enabled' => true,
    'signingSecret' => App::env('SUPER_IMAGES_SIGNING_SECRET'),
    'urlTtl' => 3600,
    'maxWidth' => 4096,
    'maxHeight' => 4096,
    'maxPixels' => 20_000_000,
],
Flow when deferred:
Twig emits signed URL
        ↓
Browser requests /actions/super-images/runtime/generate?...
        ↓
Verify signature → generate → 302 → storage URL

If runtime.enabled is false and generateBeforePageLoad is also false, Super Images still sync-generates so templates do not 404.

Thumbnail src

picture() can put a tiny server-generated storage URL in <img src> while full candidates stay in srcset / <source>. See Twig.

'delivery' => [
    'generateBeforePageLoad' => true,
    'thumbnail' => [
        'enabled' => true,
        'width' => 32,
        'format' => 'jpg',
        'quality' => 50,
        'variant' => 'thumb',
    ],
],

Locks

GenerationLockService prevents stampedes when many clients request the same missing derivative simultaneously.


Security notes

  • Do not put secrets in identity hashes, markers, or Twig output.
  • Runtime limits reject oversized geometry requests.
  • Local/remote sources still require allow-lists.
  • CSRF is disabled on the runtime action because requests are GET-signed redirects from <img> tags.