Shopify Finishes a 10-Month Expansion of Its Theme Performance Docs

Shopify has finished a 10-month expansion of the performance best practices section of its theme documentation. Dan Gayle, the Shopify web performance engineer who led it, announced the completion on LinkedIn and dated the start of the work to October 2025.

It is settled rather than closed. Gayle asked readers to report problems: “Give it a check, and if you spot anything out of wack, let me know.” The pages arrived incrementally rather than at a launch, with archived copies showing children of the performance index appearing from October 2025 through May 2026.

Gayle wrote that the original goal was “to make my own LLM agents less stupid”, assembling material from Shopify’s performance blog, performance commits in the Dawn and Horizon themes, and internal discussions. That shows in the shape of it: 68 short pages carrying one recommendation each, rather than a handful of long articles.

What the section covers

The material is grouped into nine areas: performance metrics, six essential practices, Liquid, images, JavaScript, CSS and fonts, resource hints and CDN, mobile experience, and Shopify’s platform infrastructure, plus nine measurement and strategy guides.

Most of it is platform-specific in a way that generic advice is not. Individual pages cover moving metafield access outside Liquid loops, avoiding variant overfetching, using the Section Rendering API, reserving space for app-injected content, and reducing mega menu DOM overhead. Others are portable: setting fetchpriority="high" on the LCP image, never lazy-loading it, self-hosting web fonts, and using import maps for modules.

Some pages carry numbers that matter beyond performance. Limit pagination depth to improve query performance recommends capping pagination at 25,000 objects, working through to “Maximum 500 pages: 25,000 / 50 = 500 pages”, with 12 to 24 products per page given as the range for good performance. The page frames this as a query cost problem and does not mention crawling or indexing, but the ceiling is the same one that governs how a crawler reaches deep catalogue pages.

The docs are built to be read by agents

Gayle’s stated motive, making his own agents less stupid, matches how the pages are served. Every one of them is available as Markdown: append .md to any URL and it returns text/markdown rather than an HTML document, opening with frontmatter that names the page’s title, description, and both its HTML and Markdown addresses. The fake performance apps page has a Markdown twin at the same path. A Copy MD button sits under the heading of each page for the same purpose.

Next to it is an Install AI Toolkit button, which is the larger provision. The Shopify AI Toolkit connects a coding agent to Shopify’s documentation and API schemas, validates GraphQL, Liquid and Extensions against Shopify’s own schemas, and runs store-management tasks through the authenticated Shopify CLI context. Supported tools are Claude Code, Codex, Antigravity CLI, Cursor, Visual Studio Code, and Hermes, which the docs mark plugin-only. Installation is either a plugin that updates itself, individual agent skills that do not, or a local Dev MCP server that needs no authentication.

Two things follow for anyone weighing agent-readiness work. Shopify serves no llms.txt on the developer domain, which is consistent with Google’s position that its systems do not use the file, and with the format’s status as a convention rather than a standard. And the provision that does exist is aimed at coding agents building on the platform rather than at crawlers gathering answers, which is a different job from the one llms.txt was proposed for.

Where the docs meet Google’s page experience guidance

Core Web Vitals are where the two sets of documentation meet. Google states that they are “used by our ranking systems”, while also stating there is no single page experience signal and that good scores alone do not guarantee ranking.

Remove or reduce intrusive interstitials on mobile cites Google’s guidance directly, noting that “Google’s guidance on mobile interstitials specifically calls out content that’s covered immediately after a customer arrives from search”, and adds a mechanical reason on top of the policy one: “a dialog injected during page load can become the Largest Contentful Paint element, which makes your LCP reflect the dialog rather than your content.”

Intrusive interstitials appear on Google’s page experience self-assessment list alongside Core Web Vitals, HTTPS, mobile display and ad density. Shopify’s version tells a theme developer what to change.

The framing page, Build a sustainable performance practice, argues that “performance is an ongoing practice, not a one-time project”, that real user monitoring “should drive your priorities”, and that stores degrade through “death by a thousand cuts” as apps, features and design changes accumulate.

Shopify documents the speed apps that cheat the tests

Identify and remove fake performance apps states that “some ‘speed optimization’ services cheat performance testing tools by detecting when those tools are running and serving altered pages that score well but provide no real benefit”, and describes the mechanism: the script “distinguishes between them by fingerprinting the client at the top of the document, before anything else runs.”

That is one of two techniques the page describes, and Shopify’s verdict on it is that “real users get none of that benefit. This is the most damaging variant because the numbers you’re shown describe a page that no shopper ever receives.” The second is LCP manipulation, where the script injects “an element that paints almost immediately and covers the viewport”, so “the reported LCP drops because the metric now describes a different element”. That element is served to everyone, so “field data and lab data agree, which makes the manipulation look like a genuine win”.

Its recommendation is to check a change against “pixels painting sooner or interactions responding sooner” rather than against the score, on the grounds that “Core Web Vitals are proxies for the experience, not the experience itself. A proxy can be satisfied without the thing it stands for improving at all.”

Google’s page experience documentation reaches a similar conclusion from the other direction, stating that a good report result “doesn’t guarantee that your pages will rank at the top of Google Search results” and that “trying to get a perfect score just for SEO reasons may not be the best use of your time.”

What the numbers say about speed and conversion

Shopify published its own analysis in April 2026, drawn from actively selling stores rather than a third-party study. It reports that “for every 100 milliseconds slower a store loads, conversion tends to be about 3.5% lower”, and that “stores with 2.5 second LCP report roughly 30% lower conversion than stores with 1.5 second LCP”. Responsiveness tracks the same way: “For every 32 milliseconds slower a store responds to interactions, conversion tends to drop by about 1.5%.”

The method was to bucket stores by performance: “For each metric, we divided all sites into buckets depending on their aggregated performance during a 28-day period at the turn of January and February 2026. We then looked at the relationship between the aggregated performance and the median conversion rate of the stores in every bucket.” The slowest 5% were excluded as outliers.

That is a comparison between different stores, not a before-and-after test on the same store. It establishes that faster stores convert better; it does not establish that a given store shaving 100 milliseconds gains 3.5%. Shopify’s own wording, “tends to be”, carries that distinction. It is also Shopify’s data about Shopify stores.

The same analysis puts the platform baseline high: “nearly 80% of Shopify stores pass all Core Web Vitals thresholds”. Passing is the norm on the platform rather than a point of difference.

That figure has independent support. HTTP Archive’s 2025 Web Almanac, using Chrome User Experience Report data from its July 2025 crawl, put 76% of Shopify origins passing all three Core Web Vitals on mobile, against 35% for WooCommerce and 35% for Magento. The web as a whole passed at 48% on mobile.

Where to start on a Shopify store

For anyone working on a Shopify store, the section replaces generic page speed advice with instructions written against the platform’s own rendering model.

Start with the measurement guides rather than the recommendations, because they establish which pages are worth fixing: Lab vs. field data, Testing for performance, Finding and ranking your worst JavaScript offenders, and Optimizing for Interaction to Next Paint.

The fake performance apps page is the immediate audit item. If a store runs a speed optimisation app and its Lighthouse score is markedly better than its field data in the Core Web Vitals report, the gap is worth investigating before the score is used to justify anything. That comparison only catches the first technique, though: under LCP manipulation the injected element reaches real users too, so both datasets improve together. For that one the page’s checks are to read which element the diagnostics name as the Largest Contentful Paint, and to compare the filmstrip at that timestamp against the frame where the hero image actually appears.

Sources

• Performance best practices for Shopify themes — Shopify
• Identify and remove fake performance apps — Shopify
• Build a sustainable performance practice — Shopify
• Dan Gayle’s announcement — LinkedIn
• Understanding page experience in Google Search results — Google Search Central
• Understanding Core Web Vitals and Google search results — Google Search Central
• How store speed affects conversion — Shopify
• Ecommerce — The 2025 Web Almanac by HTTP Archive
• Performance — The 2025 Web Almanac by HTTP Archive
• Shopify AI Toolkit — Shopify