Configuration 

SourceSetViewHelper 

The SourceSetViewHelper generates responsive <img> tags with srcset attributes.

{namespace nr=Netresearch\NrImageOptimize\ViewHelpers}

<nr:sourceSet path="{f:uri.image(image: image)}"
              width="1200"
              height="800"
              alt="{image.properties.alternative}"
              sizes="(max-width: 768px) 100vw, 50vw"
/>

Encoding quality 

The encoding quality is not configurable per ViewHelper call -- there is no quality argument. Generated URLs always carry the default quality of 75 (for example /processed/fileadmin/image.w1200h800m0q75.jpg), and variant requests that carry no q value are processed with the same default.

Source set configuration 

Define source sets per media breakpoint via the set attribute:

<nr:sourceSet
    path="{f:uri.image(
        image: image,
        width: '960',
        height: '690',
        cropVariant: 'default'
    )}"
    set="{
        480:{width: 160, height: 90},
        800:{width: 400, height: 300}
    }"
/>

Render modes 

cover

Default. Resizes images to fully cover the provided width and height.

fit

Resizes images so they fit within the provided width and height.

<nr:sourceSet
    path="{f:uri.image(
        image: image,
        width: '960',
        height: '690',
        cropVariant: 'default'
    )}"
    width="960"
    height="690"
    mode="fit"
/>

Lazy loading 

Both modes support lazy loading via the native loading="lazy" attribute. When using JS-based lazy loading (class="lazyload"), the data-srcset attribute is added automatically.

Backward compatibility 

By default responsiveSrcset is false, preserving the existing 2x density-based srcset behavior. All existing templates continue to work without modifications.

Trusted storage symlinks 

The processor validates that both the source image and the target variant resolve (via realpath()) to a location inside an allowed root -- the public webroot, or a Local FAL storage's own base path -- before reading or writing anything. This rejects requests for images reached through a symlink that escapes those roots (for example a symlink accidentally or maliciously pointing at /etc).

Some deployments relocate TYPO3 core's own _processed_ image cache -- a subdirectory inside a FAL storage's own directory, e.g. fileadmin/_processed_ -- onto local/ephemeral storage, to keep frequently-rewritten derivative images off shared/NFS storage. That leaves only a symlink behind inside the storage, which the FAL-storage basePath lookup above does not see (it only resolves the storage's own base path, never looks inside it), so variant requests for such images are rejected even though the original file is legitimately part of the deployed application.

The additionalTrustedStorageSymlinks extension configuration setting closes this gap on an explicit, per-instance, opt-in basis: a comma-separated list of directory names that, when found as a symlink directly inside a Local FAL storage's base path, are resolved and added to the allow-list too.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['additionalTrustedStorageSymlinks'] = '_processed_';

The setting can also be edited via the backend: Admin Tools > Settings > Extension Configuration > nr_image_optimize.

Additional trusted roots 

Some deployments need to serve variants of images that live under an absolute filesystem path that is neither the public webroot, a Local FAL storage's own base path, nor one of the hardcoded TYPO3-internal locations (var/, symlinked processed/uploads, or extension-published _assets/<hash> directories) -- for example a custom mount managed outside of FAL.

The additionalTrustedRoots extension configuration setting closes this gap on an explicit, per-instance, opt-in basis: a comma-separated list of absolute filesystem paths that are realpath-resolved and added to the allow-list directly.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['additionalTrustedRoots'] = '/mnt/custom-assets';

The setting can also be edited via the backend: Admin Tools > Settings > Extension Configuration > nr_image_optimize.

WebP/AVIF output quality 

The primary variant's quality is controlled per-request via the q<n> URL segment. The .webp and .avif sidecars previously reused that same numeric quality, but AVIF's quality scale is steeper than WebP's or JPEG's -- at matching numbers an AVIF file comes out larger than the WebP sidecar, defeating the point of serving AVIF at all.

Two extension configuration settings control sidecar quality independently of the primary variant:

qualityWebp (default 75)

Output quality for the generated WebP variant.

qualityAvif (default 60)

Output quality for the generated AVIF variant. The lower default keeps AVIF variants genuinely smaller than WebP while staying visually comparable.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['qualityWebp'] = 75;
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['qualityAvif'] = 60;

The settings can also be edited via the backend: Admin Tools > Settings > Extension Configuration > nr_image_optimize.