Formats
Generates WebP and optional AVIF siblings from JPEG, PNG and GIF sources. AVIF is off by default and needs library support.
Image Optimisation
VIDEO WALKTHROUGH
2:38 Image Optimisation: setup guide
Recorded on version 1.0.3 · Narrated walkthrough · English captions
Jump to a chapter 8 chapters
Read the full video transcript
Image Optimisation 1.0.3 — Magento Admin setup 00:00:00 — Set up Image Optimisation Welcome to the Agentic Ecom Image Optimisation Admin guide. We'll walk through the main setup screens and the checks to make before using the module. This guide assumes the extension is already installed. 00:00:13 — Open settings and choose scope Start in Magento Admin and open Stores, Configuration. Choose Image Optimisation. Check the Scope selector before editing. Use the appropriate website or store view where the setting supports it. The screen values here are a demonstration; enter the settings and service details that belong to your own store. 00:00:35 — Choose generated image formats In Format Conversion, review the WebP and available A V I F settings and their quality choices. The module generates alternate files alongside the originals. A V I F depends on image-library support, so verify the server can create that format before relying on it. 00:00:54 — Review upload resizing In Upload Resize and Retina, choose dimensions and the optional higher-density behaviour appropriate to your catalogue. Test a representative image before changing upload rules across a production store. Check the resulting dimensions and appearance on both large and small screens. 00:01:11 — Review lazy loading separately Review the optional H T M L lazy-loading settings and any exclusions. Image conversion and lazy loading solve different parts of delivery. Check important above-the-fold product images in a real browser so that a loading rule does not delay the image the customer is trying to see. 00:01:31 — Connect generated files to delivery Review Advanced WebP Conversion Settings, then use the documented command-line or cron process on a staging sample. This release returns the original Magento image URL; it does not automatically add picture markup or change Graph Q L image URLs. Configure your theme or delivery layer to serve the generated formats and verify the browser response. 00:01:55 — Save and verify your setup When your required settings are complete, use the screen's Save control and wait for Magento's confirmation. Then reopen the record or configuration and check the saved values at the intended scope. If the storefront still shows earlier settings, refresh the relevant caches. Test your own configuration before using it with customers. 00:02:16 — Your setup checklist That's the Admin setup walkthrough for Image Optimisation. Check permissions and scope, review the module-specific settings, then save and verify a small staging example. Use the written guide at user guides dot Agentic Ecom dot net for installation details, complete field references and any separate storefront integration steps.
Image Optimisation 1.0.4 generates WebP and, when your image library supports it, AVIF files beside Magento images. The original files stay in place. The module logs generated file sizes and status in AgenticEcom → Image Optimisation. Version 1.0.3 gives the standalone package an independent Admin configuration tab.
Install
Section titled “Install”The Composer commands below are for a direct AgenticEcom purchase. If you bought this extension through Adobe Commerce Marketplace, use the purchased Composer package from repo.magento.com with Adobe Marketplace access keys; see Getting Started. A Marketplace purchase should not require a second AgenticEcom direct-store licence.
Install with your AgenticEcom licence key from My Licences:
composer config repositories.agenticecom composer https://repo.agenticecom.netcomposer config --global --auth http-basic.repo.agenticecom.net <YOUR-LICENCE-KEY> xcomposer require agenticecom/module-image-optimisation:^1.0.4php bin/magento setup:upgrade && php bin/magento setup:di:compile && php bin/magento cache:flushCheck the exact release’s Magento/PHP requirements and your image library’s format support before deployment.
What the package does
Section titled “What the package does”Engine
Uses Imagick only when that installation supports the chosen format, with GD as fallback. The output depends on available codecs.
Schedule
Processes registered pending images through cron or CLI. Optional page-load mode generates missing files while a product image URL is resolved.
Optional hooks
Can downscale new JPEG/PNG uploads and add native lazy loading to HTML images. Both settings are off by default.
Process an existing catalogue
Section titled “Process an existing catalogue”-
Run
bin/magento agenticecom:image:scanto register existing catalogue gallery images as pending. -
Run
bin/magento agenticecom:image:optimize --pending-onlyto generate the enabled formats. Add--batch-size=200to limit a pending run. Magento cron also processes up to 50 pending records every five minutes when cron is running. -
Inspect the Manage Images log and generated files. The log records actual original and generated file sizes; smaller output and faster pages are not guaranteed.
Without --pending-only, agenticecom:image:optimize walks supported image files under the Magento media directory. This is broader than the catalogue gallery scan, so review the media tree and back up originals before a full run.
Command reference
Section titled “Command reference”| Command | Use |
|---|---|
agenticecom:image:scan | Register existing catalogue gallery images as pending without converting them. |
agenticecom:image:optimize --pending-only | Generate enabled formats for pending records. |
agenticecom:image:optimize --pending-only --batch-size=200 | Limit a pending pass to 200 records. |
agenticecom:image:optimize | Walk supported images throughout Magento’s media directory. The batch-size option does not limit this mode. |
catalog:images:resize | Magento’s separate command for rebuilding its resized cache renditions. |
Run CLI backfills from the Magento root as a user that can write pub/media. The scan prints registered, skipped and error counts. For a large catalogue, use pending batches and check generated files after each run. Existing generated siblings are normally skipped; changing a quality setting does not by itself replace those files.
bin/magento agenticecom:image:scanbin/magento agenticecom:image:optimize --pending-only --batch-size=200find pub/media/catalog/product -name '*.webp' -not -path '*/cache/*' | wc -lPage-load and upload settings
Section titled “Page-load and upload settings”In the page-load modes, the product-image URL hook generates missing siblings for original and resized cache images synchronously. It returns the original URL. Use cron or CLI modes if you need to avoid conversion work during that product-image request. The package has no asynchronous page-load mode.
When enabled, the upload hook can downscale oversized JPEG/PNG images as the uploader saves them. This alters the saved upload, so test quality and keep a source backup. It does not generate retina variants. The inactive CMS and retina Admin controls were removed in 1.0.2; dedicated generation and delivery paths are not included.
When enabled, the HTML response hook adds loading="lazy" after the first configured number of <img> elements and skips configured CSS classes. It does not identify the actual visual LCP image, so check important images in your theme. Headless storefronts need their own lazy-loading implementation.
The generator rejects unsupported MIME types, sources above 30 MB, either dimension above 12,000 px, and images above 50 million pixels before decoding. Imagick resource limits are configured. Test malformed files, transparency, color, memory use and output quality on the exact release and host.
If files do not appear
Section titled “If files do not appear”- Check Stores → Configuration → AgenticEcom Image Optimisation → Image Optimisation and enable WebP or supported AVIF generation. Both formats disabled means there is no conversion work.
- Confirm the CLI or PHP user can write to
pub/media; inspect file ownership and log errors. A zero error count does not prove the files are present. - Check whether the installed Imagick or GD build can encode AVIF. The CLI warns when AVIF is configured but unavailable. WebP and AVIF support depend on the host’s installed codecs.
- Check the generated sibling on disk, then check the storefront response separately. A generated
.webpfile alone does not make the browser request it.
The Admin Manage Images view is under AgenticEcom -> Image Optimisation. Its recorded sizes are observations from generated files; compare the actual transfer sizes and LCP on the complete storefront.
Will browsers automatically get WebP or AVIF?
No. The buyer package writes alternate files beside originals but does not select them in storefront HTML or GraphQL. Configure the theme or delivery layer separately.
Will converting an image delay a shopper request?
It can in page-load mode because generation runs synchronously for a missing sibling. Cron and CLI processing move that work to scheduled or manual runs.
Does the scan include CMS and retina images?
The pending scan reads catalogue gallery images. A full CLI run walks Magento’s media directory. Version 1.0.2 removes inactive CMS and retina Admin controls. It does not include dedicated CMS or retina delivery paths.