--- title: "Configuration" manual: "Image Optimization for TYPO3" version: "1.6" permalink: "https://docs.typo3.org/permalink/netresearch/nr-image-optimize:configuration@1.6" source: "Configuration/Index.rst" rendered: "2026-09-25T10:18:05+00:00" --- # Configuration {#configuration} The extension works out of the box with sensible defaults. Images are automatically optimized when accessed via the `/processed/` path. ## SourceSetViewHelper {#configuration-viewhelper} The `SourceSetViewHelper` generates responsive `` tags with `srcset` attributes. **Basic ViewHelper usage** ```html {namespace nr=Netresearch\NrImageOptimize\ViewHelpers} ``` ### Parameters {#configuration-parameters} - **path** - *Type:* string - *Required:* true Public path to the source image (for example `/fileadmin/foo.jpg`), typically generated via `f:uri.image()`. - **width** - *Type:* int|float - *Default:* 0 Base width in pixels for the rendered ``. `0` resolves automatically from the source file. - **height** - *Type:* int|float - *Default:* 0 Base height in pixels. `0` preserves aspect ratio relative to [width](https://docs.typo3.org/permalink/netresearch/nr-image-optimize:confval-confval-width@1.6). - **set** - *Type:* array - *Default:* \[\] Responsive set in the form `{maxWidth: {width: int, height: int}}`. Each entry becomes a `` tag. - **alt** - *Type:* string - *Default:* empty string Alternative text (accessibility). HTML-escaped. - **title** - *Type:* string - *Default:* empty string Title attribute for the image. HTML-escaped. - **class** - *Type:* string - *Default:* empty string CSS classes for the `` tag; include `lazyload` to use JS lazy load. - **attributes** - *Type:* array - *Default:* \[\] Extra HTML attributes merged into the rendered tag. - **lazyload** - *Type:* boolean - *Default:* false Add `loading="lazy"` (native lazy loading). - **sizes** - *Type:* string - *Default:* auto, (min-width: 992px) 991px, 100vw Responsive `sizes` attribute for the generated `` tag. - **mode** - *Type:* string - *Default:* cover Render mode. `cover` resizes images to fully cover the given dimensions. `fit` resizes images to fit within the given dimensions. - **responsiveSrcset** - *Type:* boolean - *Default:* false Enable width-based responsive `srcset` instead of density-based `2x` srcset. - **widthVariants** - *Type:* string|array - *Default:* 480, 576, 640, 768, 992, 1200, 1800 Width variants for responsive `srcset` (comma-separated string or array). - **fetchpriority** - *Type:* string - *Default:* empty string Native HTML `fetchpriority` attribute. Allowed values: `high`, `low`, `auto`. Omitted when empty. ## Encoding quality {#configuration-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. > [!NOTE] > As of this version the default variant quality is 75. Earlier > versions encoded WebP and AVIF variants at quality 100, so > those variants are now generated with stronger compression and > accordingly lower fidelity. The quality value is part of the > generated file name, so all previously generated variants > become stale and are recreated on demand under their new name. > Use [Clear processed images](https://docs.typo3.org/permalink/netresearch/nr-image-optimize:maintenance-clear@1.6) to remove > the obsolete files. ## Source set configuration {#configuration-source-sets} Define source sets per media breakpoint via the `set` attribute: **Source set with breakpoint-specific dimensions** ```html ``` ## Render modes {#configuration-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. **Using fit mode** ```html ``` ## Lazy loading {#configuration-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 {#configuration-backward-compatibility} By default [responsiveSrcset](https://docs.typo3.org/permalink/netresearch/nr-image-optimize:confval-confval-responsive-srcset@1.6) is `false`, preserving the existing 2x density-based `srcset` behavior. All existing templates continue to work without modifications. ## Trusted storage symlinks {#configuration-trusted-storage-symlinks} The additionalTrustedStorageSymlinks extension configuration setting. 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. **config/system/additional.php** ```php $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*. > [!WARNING] > **Attention** > > This widens the set of filesystem locations the processor > will read from and publicly serve variants of. Only add > well-known, infrastructure-managed names here -- never a > name an untrusted party (e.g. an FTP-only content account) > could create on their own. The default is empty, which > keeps today's behavior unchanged for every installation that > does not configure it. ## Additional trusted roots {#configuration-additional-trusted-roots} The additionalTrustedRoots extension configuration setting. TYPO3's var/ directory is now trusted automatically. 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/` 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. **config/system/additional.php** ```php $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*. > [!WARNING] > **Attention** > > This widens the set of filesystem locations the processor > will read from and publicly serve variants of. Only add paths > you fully trust. Relative paths are rejected outright (never > resolved against the PHP process's working directory). The > default is empty, which keeps today's behavior unchanged for > every installation that does not configure it. ## WebP/AVIF output quality {#configuration-sidecar-quality} The qualityWebp and qualityAvif extension configuration settings. The primary variant's quality is controlled per-request via the `q` 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. At `100` the WebP variant is encoded lossless and typically comes out several times larger than the primary JPEG 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. AVIF output quality is capped at 99: qualityAvif for the AVIF variant, and the URL quality (q100) for processed AVIF originals. At 100 ImageMagick switches to lossless AVIF encoding, which returns no image data, so no AVIF variant was written and a processed AVIF original failed with HTTP 500. **config/system/additional.php** ```php $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*. > [!WARNING] > **Attention** > > Per-format quality is not part of the processed-variant cache > filename. Changing either setting only affects newly generated > variants -- clear already-processed images (see > [Clear processed images](https://docs.typo3.org/permalink/netresearch/nr-image-optimize:maintenance-clear@1.6)) to apply the new quality to existing > ones. ## WebP/AVIF generation {#configuration-sidecar-formats} The generateWebp and generateAvif extension configuration settings. By default the processor writes a `.webp` and an `.avif` file next to every processed variant. Two switches turn either format off for the whole installation, for example to save storage when one sidecar format is enough: - **`generateWebp` (default `1`)** Write a `.webp` sidecar for each processed variant. - **`generateAvif` (default `1`)** Write an `.avif` sidecar for each processed variant. **config/system/additional.php** ```php $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['generateWebp'] = false; $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_image_optimize']['generateAvif'] = true; ``` The per-URL `skipWebP` and `skipAvif` query parameters still apply on top: a format is generated only if its switch is on and the URL does not skip it. > [!WARNING] > **Attention** > > The switches only control generation. Sidecars already on disk are > still served. Clear already-processed images (see > [Clear processed images](https://docs.typo3.org/permalink/netresearch/nr-image-optimize:maintenance-clear@1.6)) to remove them.