Images
Two image surfaces, two fix paths: Product Images (via Admin API) and Store Files (via Files library).
Don't conflate Product Media with Store Files
A product image typically lives in two independent places: the product's Media (what Shopify shows on the Product page) and the Files library at /cdn/shop/files/* (what theme JSON templates reference). Optimising product media does not automatically update theme references that point at a Files-library copy. The Images tool exposes both paths as separate tabs.
Surface 1 — Product Images
The Product Images tab targets product media accessible via the Shopify Admin API. For each image, ProRank can run Optimize & Replace: attach the optimised image as new product media, verify it loaded successfully, reorder so it occupies the original position, then delete the original.
The flow is built around replaceProductMediaWithOptimizedImage, which is replace-safe: if any step fails (upload, verify, reorder), the original media stays in place and you get an error message on the row.
- Per-row Optimize & Replace from the table.
- Bulk Optimize & Replace with a per-run cap of
BULK_IMAGE_REPLACE_LIMIT = 10rows. - Resize cap is roughly 1920px on the long edge / ~1MP — anything larger is downscaled before compression.
- Format choice is automatic based on enabled formats, optimizer support, and the original file type.
Optimize & Replace does not keep an in-app rollback. Once the original media is deleted, the revert path is to re-upload the original from your own backup. This is why the verify step runs before the delete.
Surface 2 — Store Files (theme images)
The Store Files tab targets files in the Shopify Files library. These are the assets theme JSON / Liquid templates reference (hero images, lifestyle photos, trust badges, custom section images). Replacement uses the Files API's in-place fileUpdate — the file reference is preserved, theme references keep working, and alt text is preserved unless the action explicitly changes it.
Because the file id is preserved, theme templates do not need to be edited. This is the right fix path for oversized hero / banner images that the audit calls out on key templates.
Files tab → pick a file → Optimize → preview before/after
→ Replace (calls fileUpdate)
→ File id is preserved, theme refs keep workingSome theme templates reference an old copy of an image that was uploaded to the Files library separately from the product's media. In that case, you may need to use Theme SEO Controls — image reference swap to point the template at the optimised file instead. That action requires the write_themes scope.
Smart compression — quality offsets
ProRank's "smart" mode tunes quality per format and per source resolution. Larger source images can tolerate steeper compression without visible quality loss; the offsets below are applied on top of the base target quality.
| Format | Offset | Minimum quality | Notes |
|---|---|---|---|
| JPEG / JPEGli | -15 from base quality | 40 | JPEGli is used only when the optimizer runtime has it available; high-DPI sources get an additional -10. |
| WebP | -20 from base | 40 | WebP q60 ≈ JPEG q75 visually. |
| AVIF | -30 from base | 35 | AVIF has a file-size cliff between q50 and q55; offset is intentional. |
Source-size tiers (applied before format offset): >8 MP gets -25 (min 45), >4 MP -20 (min 50), >2 MP -15 (min 55), >1 MP -10 (min 60). High-DPI sources (>2 MP and ≥ 2x intrinsic-to-render ratio) get an additional -10 (min 45).
Missing alt text — the honest scope
The audit's missing_alt_text rule reads product media alt text from Shopify (for example product.media.preview.image.altText). It does not guarantee coverage for every theme-rendered image on the live storefront.
Two consequences:
- Trust badges, decorative icons, Shopify video posters, theme rich-text images, and similar theme assets are out of scope. They live in theme templates or in Files, not in product Media.
- Decorative images should keep
alt=""per WCAG. Bulk auto-generating descriptive alt onto decorative icons is a regression, not a fix. Use judgment — when the audit row is "site icon" or "trust badge", confirm before applying.
Where this lives
Routes & services
app.images.tsxreplaceProductMediaWithOptimizedImagereplaceShopifyFileWithOptimizedImage
Settings
Optimizer URL, formats enabled, smart compression on/off, and per-format target qualities live under the Images tab's Settings panel. Defaults are conservative and tuned for visual parity with the original.