Usage 

Register the namespace 

Add the ViewHelper namespace at the top of your Fluid template or register it globally:

{namespace nr=Netresearch\NrImageOptimize\ViewHelpers}

Basic responsive image 

<nr:sourceSet file="{image}"
              width="1200"
              height="800"
              sizes="(max-width: 768px) 100vw, 50vw"
/>

Quality is not configurable per call: the ViewHelper always emits its default quality of 75 into the generated /processed/...q<n>... URL.

Responsive width-based srcset 

Enable width-based srcset generation with a sizes attribute for improved responsive image handling. This is opt-in per usage.

<nr:sourceSet
    path="{f:uri.image(
        image: image,
        maxWidth: size,
        cropVariant: 'default'
    )}"
    width="{size}"
    height="{size * ratio}"
    alt="{image.properties.alternative}"
    lazyload="1"
    mode="fit"
    responsiveSrcset="1"
/>

<nr:sourceSet
    path="{f:uri.image(
        image: image,
        maxWidth: size,
        cropVariant: 'default'
    )}"
    width="{size}"
    height="{size * ratio}"
    responsiveSrcset="1"
    widthVariants="320,640,1024,1920,2560"
    sizes="(max-width: 640px) 100vw,
           (max-width: 1024px) 75vw, 50vw"
/>

Output comparison 

Legacy mode (responsiveSrcset=false or not set):

<img src="/processed/fileadmin/image.w625h250m1q75.jpg"
     srcset="/processed/fileadmin/image.w1250h500m1q75.jpg x2"
     width="625"
     height="250"
     loading="lazy">

Responsive mode (responsiveSrcset=true):

<img src="/processed/fileadmin/image.w1250h1250m1q75.png"
     srcset="/processed/fileadmin/image.w480h480m1q75.png 480w,
             /processed/fileadmin/image.w576h576m1q75.png 576w,
             /processed/fileadmin/image.w640h640m1q75.png 640w,
             /processed/fileadmin/image.w768h768m1q75.png 768w,
             /processed/fileadmin/image.w992h992m1q75.png 992w,
             /processed/fileadmin/image.w1200h1200m1q75.png 1200w,
             /processed/fileadmin/image.w1800h1800m1q75.png 1800w"
     sizes="auto, (min-width: 992px) 991px, 100vw"
     width="991"
     loading="lazy"
     alt="Image">

Public images only: absolute URLs are passed through 

The /processed/ endpoint is designed for public files only. It resolves the given path below the public web root and writes the generated variants as static files into public/processed/, where the web server delivers them directly — without any access check.

Files in non-public FAL storages (is_public = 0) can therefore not be processed.

Extensions such as fal_securedownload resolve such files to tokenized eID URLs (/index.php?eID=dumpFile&...) whose delivery runs through TYPO3 and performs a permission check on every request.

The ViewHelper detects absolute URLs (http://, https://, //), data: URIs, and URLs containing a query string and passes them through unchanged, rendering a plain <img> tag with the URL as src:

<picture>
<img src="https://example.org/index.php?eID=dumpFile&amp;t=f&amp;f=42&amp;fal_token=..."
     width="400"
     height="300"
     alt="Protected image" />
</picture>

If you need optimized variants of images in protected storages, generate them with TYPO3's own image processing (for example f:image or the ImageService). Processed files are then created inside the protected storage's processing folder and are delivered through the same secure-download mechanism, keeping the permission check intact.

Fetch priority for Core Web Vitals 

Use the fetchpriority attribute to hint the browser about resource prioritization, improving Largest Contentful Paint (LCP) scores:

<nr:sourceSet file="{heroImage}"
              width="1920"
              height="1080"
              fetchpriority="high"
/>

Skip WebP or AVIF generation 

By default the first request for a variant writes the source format plus a .webp and an .avif sidecar. AVIF encoding is the most expensive of the three. Set skipAvif and/or skipWebP to leave a format out for one ViewHelper call; the flag is added to every URL the call renders:

<nr:sourceSet path="{f:uri.image(image: image)}"
              width="1200"
              height="800"
              skipAvif="1"
/>

With both flags set, each variant is written in its source format only.

Command-line tools 

Both commands read the FAL index directly and process eligible image files (image/jpeg, image/gif, image/png) on online storages. Per-file storage permission evaluation is temporarily disabled and restored in a finally block so long-running CLI runs don't leak state across iterations or require a BE user context.

vendor/bin/typo3 nr:image:optimize --dry-run

vendor/bin/typo3 nr:image:optimize \
    --storages=1 \
    --jpeg-quality=85 \
    --strip-metadata

vendor/bin/typo3 nr:image:analyze --storages=1