Theme SEO Controls

The set of fixes that need to write into your theme files — gated behind Shopify's optional write_themes scope and protected-scope approval.

Why this tool exists

Some SEO fixes have no Admin API endpoint. There is no per-collection robots field, no way to edit /collections/all, no way to rewrite a theme template's image reference without touching the theme file itself. Theme SEO Controls fills that gap — but because it edits theme files, it requires the optional write_themes scope and Shopify's protected-scope exemption for theme file writes.

What it can do

Action	What it does	When to use
Theme image-reference swap	Rewrites image references in theme JSON / Liquid templates to point at the optimised file id.	When the optimised file lives in the Files library but the theme template still references the old copy.
Collection noindex	Inserts a robots meta in the collection template (e.g. frontpage) so a duplicate collection page is not indexed.	When /collections/frontpage or another collection duplicates the homepage and the Admin API has no noindex field.
Customer auth redirect cleanup	Removes a customer auth redirect line in the theme that causes accidental redirect chains visible to crawlers.	When the crawler audit reports an auth-page redirect on a non-auth URL.

The optional write_themes scope

ProRank declares write_themes as an optional Shopify scope. Optional scopes are not granted automatically at install. The app owner must have Shopify's protected-scope approval, release the scope with the app version, and the merchant must grant the scope explicitly from inside the app.

Until the grant is available and approved, Theme SEO Controls actions stay blocked. One common raw Shopify/App Bridge error looks like this:

RequestGrantUserError: optional scopes subset of []

In practice this means the install does not currently have the theme-write permission needed for the requested action. The UI surfaces this as a clear "Grant theme write access" prompt rather than the raw error.

Granting access

The grant lives in Visibility → Theme SEO → Grant theme write access inside the app. Clicking it triggers Shopify's standard optional-scope request flow: the merchant sees exactly what the app wants to do and approves or denies.

In-app path:  Visibility → Theme SEO → Grant theme write access
Shopify flow:  optional scope request → merchant approves
Result:        write_themes added to the install's granted scopes
Effect:        Theme SEO Controls actions become clickable

If the "Grant theme write access" button reports "optional scope not available", the scope is not available for the current app version or the app has not yet received Shopify's protected-scope approval for theme file writes. Contact support if you see this.

Safety model — preview, backup, write, verify, rollback

Theme edits are the riskiest action in the app, so the flow is deliberately conservative. Every theme-write action goes through the same five steps:

Preview diff. ProRank fetches the target asset, computes the proposed change, and shows you a unified diff before anything is written.
Backup. The original asset body is stored in the ThemeWriteBackup table, scoped to the shop and the theme id. This is what makes rollback possible without re-uploading from your local copy.
Write via themeFilesUpsert. Shopify's Admin GraphQL mutation applies the change atomically per file.
Verify. ProRank re-reads the file and confirms the change took. If verify fails, the row is marked "needs attention" rather than "done".
Rollback. Every applied action has a one-click Rollbackbutton that restores the original body from the backup. Available until the backup is pruned.

ProRank's backup is the primary rollback path for these actions. If you edit the same file again outside ProRank, use Shopify's theme editor history or your own theme backup as the secondary safety net.

Action — Theme image-reference swap

A common pattern: an old hero image lives in the Files library at one file id, and the theme JSON template references that file id. You upload a newer / optimised version of the same image, but the theme keeps pointing at the old id, so visitors still see the oversized one.

The image-reference swap action finds references to the old file id in theme JSON / Liquid and rewrites them to point at the new id. The diff makes it obvious which sections of which template are being touched.

Action — Collection noindex (template-level)

Shopify does not expose a per-collection robots field on the Admin API. The practical theme-level fix is a guarded Liquid output in the page <head> — for example in layout/theme.liquid or an app/theme block that renders there. JSON templates choose sections; by themselves they do not emit head tags.

This action targets the specific collection handle (commonly frontpage or all) and inserts a guarded noindex robots meta with backup and rollback. Useful when a duplicate collection URL is being indexed as a low value landing page.

Action — Customer auth redirect cleanup

Some theme defaults include a customer-auth redirect line that, depending on how the theme is configured, can cause an external crawler to see a redirect chain on a non-auth URL. The cleanup action removes the offending line and re-runs a verify to confirm the redirect chain is gone.

If the crawler audit row doesn't change after applying this action, the most common cause is that the action hasn't actually run yet (because the scope grant wasn't completed). Confirm the action shows as "Applied" in Theme SEO Controls before chasing the crawler.

Where this lives

Routes & services

app.theme-seo.tsx — UI
theme-seo.server.ts — preview, write, verify
theme-seo.ts — diff and patch helpers
ThemeWriteBackup Prisma model — backups

App config

In shopify.app.toml:

[access_scopes]
optional_scopes = ["write_themes"]

Images

Product Media vs Files — and when image-ref swap kicks in.

Troubleshooting

Scope errors, rollback, and verify-failed states.

Theme SEO Controls is reviewed for safety on every release — backups and rollback are first-class, not an afterthought.