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. It first creates and verifies a backup in Shopify Files, attaches the optimised image, confirms that it loaded, and returns it to the original position. Only then does ProRank detach the old image from that product. It does not globally delete the old file, which avoids removing a file that another product or theme may still use.
The replacement process is designed to be safe: if the upload, verification, or reorder step fails, the original media stays in place and the row shows what went wrong. Completed jobs appear in Image Jobs with their backup and restore status.
- Per-row Optimize & Replace from the table.
- Bulk Optimize & Replace for up to 10 selected images at a time.
- Choose an output format in the Images tool; your saved preference is selected by default.
30-day, conflict-safe restore
ProRank retains the verified Shopify Files backup for 30 days. Use Restore in Image Jobs to attach a restored copy at the original position and detach the optimised version. Before changing anything, ProRank checks that the current product media still matches the completed job. If you or another app changed it later, restore stops instead of overwriting newer work.
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 or banner images you identify in the Files library.
Store Files replacements also create a verified backup retained for 30 days. Restore runs in place from Image Jobs, but only after confirming that the file still matches the optimized version recorded by the job. A later merchant or app change is left untouched.
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
ProRank tunes compression for the selected output format while preserving a quality floor. Preview the result before replacement so you can compare the optimized image with the original on the content that matters to your store.
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 Images tool's separate storefront scan reports a site icon or trust badge, and confirm before applying a change.
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.