--- description: Store performance architecture for our themes — CSS/JS tiering, third-party containment, images, Section API, and maintenance checklist globs: - "_scripts/**" - "_styles/**" - "snippets/_head*.liquid" - "snippets/_body*.liquid" - "layout/theme.liquid" - "snippets/a--image*.liquid" alwaysApply: false --- # Store Performance Guide Reference for how this theme optimizes storefront performance. Read this before adding scripts, third-party tags, CSS, or heavy Liquid to ``. ## Goals & budgets | Metric | Target | Primary levers | |--------|--------|----------------| | LCP | < 2.5s | Critical CSS, LCP preloads, font discipline, hero image sizing | | INP / TBT | Low main-thread blocking | Deferred JS, idle third-parties, smaller `index.js` | | CLS | Stable layout | Explicit image dimensions, `font-display: swap`, reserved space | | Third-party cost | Contained | Resource blocker, `content_for_header` sanitization, deferred analytics | **Source of truth for JS:** `_scripts/` → built to `assets/` via `npm run scripts:build`. Never edit `assets/*.js` directly. --- ## Page load timeline ``` ┌─ HEAD (critical path) ─────────────────────────────────────────────────────┐ │ 1. _head-resource-blocker Network + DOM patches (first script) │ │ 2. _head-urgent-script Geoblock / track-my-order redirect │ │ 3. _meta-tags, _head-seo Meta, favicons (low fetchpriority) │ │ 4. _product-preload-slider PDP: up to 5 slider images (portrait) │ │ 5. _index-preload-hero Homepage: mobile LCP hero preload │ │ 6. _head-style Fonts, :root tokens, critical.css, style.css │ │ 7. _script-variables window.theme, routes, icons SVG, Klaviyo cfg │ │ 8. debug-proxy (conditional) API proxy for preview/dev only │ │ 9. index.js [+ page bundles] Route-specific modules in head │ │10. speculationrules Conservative prerender for internal links │ │11. _head-console-filter Suppresses noisy third-party console (LH) │ │12. content_for_header Shopify apps — sanitized after capture │ │13. Post-header cleanup Removes blocked script/link nodes │ └────────────────────────────────────────────────────────────────────────────┘ ┌─ BODY ─────────────────────────────────────────────────────────────────────┐ │ Main content (sections/snippets) │ │ _body-script → deferred.js (module, end of body) │ │ → scheduleIdle → deferred-integrations.js (conditional) │ │ → klaviyo-cart-tracking.js, hotjar-deferred.js │ └────────────────────────────────────────────────────────────────────────────┘ ┌─ IDLE / INTERACTION ───────────────────────────────────────────────────────┐ │ Hotjar (8s idle or first scroll/click/touch/keydown) │ │ Rebuy product view analytics (PDP, 2s idle) │ │ Variant image prefetch (hover; touch: max 3 after 5s idle) │ │ cart.js injected when cart drawer opens │ │ electric-section lazy fetch (IntersectionObserver, often 1200px margin) │ └────────────────────────────────────────────────────────────────────────────┘ ┌─ window.load ──────────────────────────────────────────────────────────────┐ │ AddShoppers referral widget (async) │ └────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 1. CSS tiering ### Critical bundle (render-blocking) - **Source:** `_styles/critical.css` → `assets/critical.css` - **Scope:** Header + homepage hero shell only; narrow `@source` list (~12 Liquid files) - **Loaded in:** `snippets/_head-style.liquid` via `stylesheet_tag` When adding above-the-fold UI to header or index hero, ensure Tailwind classes are covered by critical `@source` paths or accept FOUC until full CSS loads. ### Full stylesheet (non-blocking) - **Source:** `_styles/main.css` → `assets/style.css` - **Pattern:** `media="print" onload="this.media='all'"` + `

` breakpoints; LCP path avoids desktop 2x retina | ### Preloads | Snippet | When | What | |---------|------|------| | `_index-preload-hero.liquid` | `request.page_type == 'index'` | Mobile 420w hero from `settings.homepage_lcp_image` | | `_product-preload-slider-images.liquid` | PDP | Up to 5 portrait slider images, `imagesrcset` 480/960 | | `_head-seo.liquid` | All | Favicons `fetchpriority="low"` | ### No lazysizes Theme uses **native `loading="lazy"`** only. `unveilLazyloadIn()` in `core-components.js` is a no-op kept for API compatibility. ### Variant image prefetch (PDP) `_scripts/product-variant-prefetch.js`: - **Desktop:** hover/focus → fetch `?section_id=api--product-images&variant={id}` → preload image URLs from JSON payload - **Touch:** after 5s idle, max **3** variants, images section only (no `product--main` fetch) --- ## 6. Navigation & prefetch ### Speculation Rules (native prerender) `snippets/_head-script.liquid` — `eagerness: "conservative"` Prerenders same-origin links except account, cart, login. Do not add instant.page alongside this. ### electric-section (Section Rendering API) `_scripts/electric-section.js`: - Lazy load via `IntersectionObserver` (`data-onload`, configurable `data-onload-root-margin`) - Fragment cache (max 10 entries) - Events: `electric-section:prefetch`, `electric-section:fetch` - Used for collection tabs, IRL, more-to-love, header fragments, etc. ### electric-pub (tab prefetch) `_scripts/electric-pub.js` — prefetches tab content on hover/focus or intersection. ### Cart script on demand `core-components.js` → `loadCartScriptOnce()` injects `cart.js` with `defer` when cart drawer opens (not on every page upfront). --- ## 7. Shopify-specific patterns ### Route-conditional head scripts From `_head-script.liquid`: ```liquid index.js → all pages productpage.js → product product--variant-radios.js → product collectionpage.js → collection, search cart.js → cart template ``` ### Geoblock When `settings.geoblock_enabled`: - `html.geoblock-pending` hides body until `/browsing_context_suggestions.json` returns - Currently **disabled** in `settings_data.json` - **Caveat:** fetch failure only warns — body can stay hidden if enabled without a fallback ### Fabric cart restoration Inline in `_head-script.liquid` — cart/product template logic for `_fabric` localStorage flow. ### Debug API proxy `_scripts/debug-proxy.js` — loads only when debug cookie, `?debug_proxy*`, or Shopify design mode. Rewrites proxy API fetch URLs. --- ## 8. Klaviyo & analytics data flow ### Cart tracking (deferred) 1. `product--form.js` dispatches `cart:added` with cart payload 2. `klaviyo-cart-tracking.js` waits for `_learnq`, pushes `Added to Cart v3` + legacy `Added to Cart` 3. Product page context from `window.theme.klaviyoCart` in `_script-variables.liquid` 4. Cart page replays `cart:added` from `sessionStorage cart:justAdded` ### Viewed Product (not deferred) `sections/product--icons-model.liquid` — large inline Klaviyo script when comparison section renders. **Candidate for future deferral.** ### Rebuy - Widget CDN blocked; custom `electric-rebuy-simplify` uses API - Product view POST deferred via `rebuy-product-view.js` - Global helpers in `_script-variables.liquid` (`rebuyTrackEvent`, session storage for added variants) --- ## 9. Adding new features — checklist ### New JavaScript - [ ] Default to `_scripts/` source file, not `assets/` - [ ] If needed on every page → consider `deferred.js` not `main.js` - [ ] If third-party → defer (idle/interaction/load), never sync in head unless unavoidable - [ ] If PDP-only → `productpage.js` or section `{% javascript %}` - [ ] Add to `.climaybe/build-scripts.js` if new bundle entry - [ ] Run `npm run scripts:build` - [ ] Use `scheduleIdle` from `utils/perf.js` for non-critical init - [ ] AbortController + cleanup in web components ### New third-party script - [ ] Can it go through GTM with consent + idle trigger instead of theme? - [ ] If app embed: expect `content_for_header` injection — add to blocker list if it conflicts (fonts, duplicate widgets) - [ ] Add domain to `_head-console-filter` only if noise is unavoidable - [ ] Never add sync analytics in `_head-script.liquid` ### New above-the-fold UI - [ ] Extend `critical.css` `@source` if new classes needed at first paint - [ ] LCP image: use `fetchpriority="high"`, explicit dimensions, preload in dedicated snippet - [ ] Do not preload more than 2 fonts ### New section below fold - [ ] `loading="lazy"` on images - [ ] Consider `` instead of bundling in `index.js` - [ ] Pass `lazyload: true` to product cards --- ## 10. Testing & measurement ### Before shipping perf changes 1. **Chrome DevTools** — Performance trace: LCP element, long tasks, third-party cost 2. **Network** — throttle Slow 4G; verify critical.css → first paint, style.css non-blocking 3. **Coverage** — how much of `index.js` executes on homepage vs PDP 4. **Block third-parties test** — block `googletagmanager.com`, `static.klaviyo.com`, `static.hotjar.com`; if TBT collapses, marketing stack is the bottleneck 5. **Theme Check** — `npm run lint:liquid` 6. **Build** — `npm run scripts:build && npm run tailwind:build` ### Debug modes | URL param | Effect | |-----------|--------| | `?debug_typekit=1` | Typekit audit (`_head-typekit-debug`) | | `?debug_rebuy=1` | Rebuy logging | | `?debug_proxy=1` | API proxy prompt | | `?debug_proxy_domain=` | Set proxy origin | --- ## 11. Known gaps & maintenance risks 1. **`collectionpage.js` / `cart.js` not in build targets** — `_scripts` edits may not reach `assets/` until manual copy or build update 2. **Many section scripts outside bundler** — verify `assets/` sync when editing `_scripts/wishlist-feed.js`, etc. 3. **Stale LiquidDoc** in `_head-script.liquid`, `_head-urgent-script.liquid` — docs mention Rebuy head prefetch, instant.page, promo anti-flash that moved or were removed 4. **`index.js` size (~340KB+)** — largest theme-controlled bottleneck; split `core-components.js` further if TBT regresses 5. **GTM / Elevar** — largest real-world cost; theme cannot fix container bloat 6. **`_head-console-filter`** — masks errors; misleading during app debugging 7. **Klaviyo Viewed Product inline** — still heavy on PDP with icons model section --- ## 12. File quick reference | Concern | Primary files | |---------|---------------| | Load order | `layout/theme.liquid` | | Resource blocking | `snippets/_head-resource-blocker.liquid` | | CSS tiering | `snippets/_head-style.liquid`, `_styles/critical.css`, `_styles/main.css` | | JS bootstrap | `snippets/_head-script.liquid`, `snippets/_body-script.liquid` | | Globals | `snippets/_script-variables.liquid` | | Build | `.climaybe/build-scripts.js`, `package.json` | | Idle utils | `_scripts/utils/perf.js` | | Images | `snippets/a--image.liquid`, `snippets/a--image-responsive.liquid` | | LCP preloads | `snippets/_index-preload-hero.liquid`, `snippets/_product-preload-slider-images.liquid` | | Section lazy load | `_scripts/electric-section.js` | | Deferred 3P | `_scripts/hotjar-deferred.js`, `_scripts/klaviyo-cart-tracking.js`, `_scripts/rebuy-product-view.js` | | App embeds | `config/settings_data.json` | --- ## 13. Related rules - `javascript-standards.mdc` — web components, layout thrashing, `scheduleIdle` patterns - `tailwindcss-rules.mdc` — static classes, `@source` for critical CSS - `project-overview.mdc` — performance targets (< 16ms init, 60fps), build outputs vs source (`_scripts/` / `_styles/`, never `assets/` directly)