A zero-dependency Node.js CLI that scans a Shopify theme's source files (the folder produced by
shopify theme pull) and reports exactly what's slowing it down — before it shows up as a bad
Lighthouse score or a lost sale.
Try the full live-site audit free → (this CLI checks the source files on disk; the live audit also measures the rendered page, real network waterfalls and SEO/CRO signals)
Slow Shopify themes lose sales. The usual culprits are easy to miss during manual review: oversized images pulled straight from a designer's export, unminified CSS/JS shipped as-is, script tags that block first render, a Google Fonts request pulling nine weights when the theme uses two, and third-party embeds (chat widgets, review apps, ad pixels) added over the years and never revisited. This tool scans a theme's checked-out source and lists exactly what to fix, with a one-line reason for each.
$ node bin/audit.js ./my-theme
Shopify Theme Performance Audit
Found 4 issue(s)
third-party-request (2)
- sections/announcement-bar.liquid
A <script> tag loads reviews-widget.example.com directly in the render path. Third-party
scripts/fonts/embeds are a common source of slow TTFB and long tasks. Confirm it's still
needed, load it with defer/async, or move it behind a consent/interaction gate.
- layout/theme.liquid
A <link> tag loads fonts.googleapis.com directly in the render path. ...
excessive-font-weights (1)
- layout/theme.liquid
A Google Fonts link requests 9 weights (budget: 4). Each extra weight is a separate font
file download that blocks text rendering. Trim to the weights the theme actually uses.
oversized-image (1)
- assets/hero-banner.jpg
Image is 842.3KB, above the 200KB budget. Compress it or serve it through Shopify's
image_url filter with explicit widths.
| Check | What it flags |
|---|---|
| Oversized images | .jpg/.jpeg/.png/.gif/.webp/.svg files over a size budget (default 200KB) |
| Unminified assets | .js/.css files over a size budget that don't look minified |
| Render-blocking scripts | <script src="..."> in .liquid files with no defer/async/type="module" |
| Third-party requests | <script>, <link>, <iframe> tags pointing at any host that isn't Shopify's own CDN — fonts, tag managers, review/chat/upsell widgets, ad pixels |
| Missing image attributes | <img> tags without width/height (CLS risk) or without a loading strategy |
| Excessive font weights | Google Fonts <link> tags requesting more wght values than the budget (default 4) |
| Possibly-unused assets | Files under assets/ whose filename never appears in any other theme file |
| Bloated JSON templates | templates/*.json files rendering more sections than a budget (default 15) |
Every issue includes the file path and a plain-English reason, not just a rule name.
git clone https://github.com/Ecom-Swift-LLC/shopify-theme-performance-auditor.git
cd shopify-theme-performance-auditor
No dependencies to install — it only uses Node's built-in fs, path and url modules.
node bin/audit.js THEME_PATH [flags]
Example: node bin/audit.js ./my-theme
Flags:
| Flag | Default | Meaning |
|---|---|---|
--json |
off | Print a machine-readable report instead of text |
--max-image-kb=N |
200 |
Image size budget in KB |
--max-asset-kb=N |
100 |
CSS/JS size budget in KB for non-minified files |
--max-font-weights=N |
4 |
Max wght values allowed per Google Fonts link |
--max-template-sections=N |
15 |
Max sections allowed per JSON template before it's flagged as bloated |
--skip-unused-assets |
off | Skip the unused-assets check (see caveat below) |
The process exits with code 1 when issues are found and 0 when it's clean, so it can be wired
into CI (for example, a GitHub Action that runs it against a shopify theme pull output on every
PR).
Be clear-eyed about the limits before you rely on this:
- It does not render the page. It reads source files as text. It cannot see the final DOM, measure actual load time, or catch performance problems that only exist after Liquid/JS run in a browser (layout thrash from a slow app block, a lazy-loaded carousel that isn't actually lazy, cumulative layout shift from a webfont swap).
- It cannot see runtime data. No Core Web Vitals field data (LCP/CLS/INP from real visitors), no Lighthouse score, no network waterfall, no TTFB.
- The unused-assets check is a heuristic, not proof. It flags a file if no other theme file
contains its filename as a string. An asset built from a Liquid variable (
{{ handle }}.js) or loaded by an app's own injected script won't be caught as "used," and could be a false positive. Always verify manually — including checking app embeds and installed Shopify apps — before deleting anything. - It does not check SEO, accessibility, or app-block performance. Third-party Shopify apps
inject their own scripts at runtime; this tool only sees what's already written into the theme's
own
.liquid/.json/.css/.jsfiles, so an app's slow embed won't show up here at all. - It does not test on a live storefront, only a locally checked-out theme directory.
For all of that — real Core Web Vitals, SEO, CRO and AI-visibility signals measured against your actual live store — run the free full audit.
Does this modify my theme? No. It's read-only — it only reads files and prints a report.
Will it work on any theme? Yes, any theme directory in the standard Shopify structure
(assets/, sections/, snippets/, templates/, layout/). Get one locally with
shopify theme pull.
Can I run it in CI? Yes — it exits non-zero when issues are found. A typical setup runs it on every PR against the pulled theme and fails the build (or just comments) when a new oversized image or third-party script sneaks in.
Why doesn't it check for unused CSS? Detecting truly unused CSS selectors reliably requires
rendering the page and diffing against document.styleSheets coverage — that's a browser-based
problem, not a static-analysis one, so it's out of scope for this tool. The unused-assets check
here is a much simpler, coarser heuristic (see above).
Issues and pull requests that add new static checks (for example, detecting !important overuse,
duplicate CSS custom properties, or missing rel="preconnect" for known font/third-party hosts) are
welcome.
--fixmode for the mechanical fixes (addingdefer, addingloading="lazy")- A GitHub Action wrapper so this runs on every theme PR with zero setup
- Optional Lighthouse CI integration for teams that want both static and runtime checks in one report
- shopify-store-audit-toolkit — the live-site version of this idea: a CLI that audits a running Shopify store's SEO, structured data, security headers, and more
- shopify-audit-mcp — connect Claude, Cursor or any MCP client to the same free audit engine
- shopify-liquid-snippets — copy-paste Liquid snippets for common theme needs
- shopify-product-recommendations — a dependency-free related-products section
- Free tools directory — every free tool we've shipped, in one place
This project is maintained by Ecom Swift LLC, a Shopify Partner.
- 🛍️ Shopify Partner Directory: https://www.shopify.com/partners/directory/partner/waowy
- ✉️ Email: support@ecomswiftllc.com
- 💬 WhatsApp: https://wa.me/16312511767
MIT
Free, no signup, three minutes: run the full Shopify store audit for real Core Web Vitals, SEO, CRO and AI-visibility findings on your live store — or browse the free tools directory for more. We're Ecom Swift LLC, a Shopify Partner (directory profile) — we built this CLI because we kept finding the same theme-performance issues by hand across client audits.