climaybe 3.4.8 → 3.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/version.txt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
3.
|
|
1
|
+
3.5.0
|
package/package.json
CHANGED
|
@@ -13,6 +13,7 @@ When you perform any of the following, **read and apply** the corresponding rule
|
|
|
13
13
|
- **Accessibility, a11y, focus, WCAG, UI behavior** → `accessibility-rules.mdc`
|
|
14
14
|
- **JavaScript, web components, _scripts/, *.js** → `javascript-standards.mdc`
|
|
15
15
|
- **Tailwind CSS, theme tokens, Liquid/CSS classes, _styles/** → `tailwindcss-rules.mdc`
|
|
16
|
+
- **Store performance, LCP/INP/CLS, head scripts, third-party tags, CSS/JS tiering, images, _head*/_body* snippets** → `performance-guide.mdc`
|
|
16
17
|
- **Liquid syntax and usage** → `liquid.mdc`
|
|
17
18
|
- **Section files (sections/*.liquid)** → `sections.mdc`
|
|
18
19
|
- **Snippets (snippets/*.liquid)** → `snippets.mdc`
|
|
@@ -52,6 +52,7 @@ These rules are synced from ~/.claude/rules/:
|
|
|
52
52
|
### Project-Specific Rules
|
|
53
53
|
These rules are unique to this project:
|
|
54
54
|
- `project-overview.mdc` - Electric Maybe theme overview
|
|
55
|
+
- `performance-guide.mdc` - Store performance architecture (CSS/JS tiering, third-party containment, LCP)
|
|
55
56
|
- `js-refactor-tasks.mdc` - Current refactoring tasks
|
|
56
57
|
|
|
57
58
|
## Important Notes
|
|
@@ -0,0 +1,436 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Store performance architecture for our themes — CSS/JS tiering, third-party containment, images, Section API, and maintenance checklist
|
|
3
|
+
globs:
|
|
4
|
+
- "_scripts/**"
|
|
5
|
+
- "_styles/**"
|
|
6
|
+
- "snippets/_head*.liquid"
|
|
7
|
+
- "snippets/_body*.liquid"
|
|
8
|
+
- "layout/theme.liquid"
|
|
9
|
+
- "snippets/a--image*.liquid"
|
|
10
|
+
alwaysApply: false
|
|
11
|
+
---
|
|
12
|
+
# Store Performance Guide
|
|
13
|
+
|
|
14
|
+
Reference for how this theme optimizes storefront performance. Read this before adding scripts, third-party tags, CSS, or heavy Liquid to `<head>`.
|
|
15
|
+
|
|
16
|
+
## Goals & budgets
|
|
17
|
+
|
|
18
|
+
| Metric | Target | Primary levers |
|
|
19
|
+
|--------|--------|----------------|
|
|
20
|
+
| LCP | < 2.5s | Critical CSS, LCP preloads, font discipline, hero image sizing |
|
|
21
|
+
| INP / TBT | Low main-thread blocking | Deferred JS, idle third-parties, smaller `index.js` |
|
|
22
|
+
| CLS | Stable layout | Explicit image dimensions, `font-display: swap`, reserved space |
|
|
23
|
+
| Third-party cost | Contained | Resource blocker, `content_for_header` sanitization, deferred analytics |
|
|
24
|
+
|
|
25
|
+
**Source of truth for JS:** `_scripts/` → built to `assets/` via `npm run scripts:build`. Never edit `assets/*.js` directly.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Page load timeline
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
┌─ HEAD (critical path) ─────────────────────────────────────────────────────┐
|
|
33
|
+
│ 1. _head-resource-blocker Network + DOM patches (first script) │
|
|
34
|
+
│ 2. _head-urgent-script Geoblock / track-my-order redirect │
|
|
35
|
+
│ 3. _meta-tags, _head-seo Meta, favicons (low fetchpriority) │
|
|
36
|
+
│ 4. _product-preload-slider PDP: up to 5 slider images (portrait) │
|
|
37
|
+
│ 5. _index-preload-hero Homepage: mobile LCP hero preload │
|
|
38
|
+
│ 6. _head-style Fonts, :root tokens, critical.css, style.css │
|
|
39
|
+
│ 7. _script-variables window.theme, routes, icons SVG, Klaviyo cfg │
|
|
40
|
+
│ 8. debug-proxy (conditional) API proxy for preview/dev only │
|
|
41
|
+
│ 9. index.js [+ page bundles] Route-specific modules in head │
|
|
42
|
+
│10. speculationrules Conservative prerender for internal links │
|
|
43
|
+
│11. _head-console-filter Suppresses noisy third-party console (LH) │
|
|
44
|
+
│12. content_for_header Shopify apps — sanitized after capture │
|
|
45
|
+
│13. Post-header cleanup Removes blocked script/link nodes │
|
|
46
|
+
└────────────────────────────────────────────────────────────────────────────┘
|
|
47
|
+
┌─ BODY ─────────────────────────────────────────────────────────────────────┐
|
|
48
|
+
│ Main content (sections/snippets) │
|
|
49
|
+
│ _body-script → deferred.js (module, end of body) │
|
|
50
|
+
│ → scheduleIdle → deferred-integrations.js (conditional) │
|
|
51
|
+
│ → klaviyo-cart-tracking.js, hotjar-deferred.js │
|
|
52
|
+
└────────────────────────────────────────────────────────────────────────────┘
|
|
53
|
+
┌─ IDLE / INTERACTION ───────────────────────────────────────────────────────┐
|
|
54
|
+
│ Hotjar (8s idle or first scroll/click/touch/keydown) │
|
|
55
|
+
│ Rebuy product view analytics (PDP, 2s idle) │
|
|
56
|
+
│ Variant image prefetch (hover; touch: max 3 after 5s idle) │
|
|
57
|
+
│ cart.js injected when cart drawer opens │
|
|
58
|
+
│ electric-section lazy fetch (IntersectionObserver, often 1200px margin) │
|
|
59
|
+
└────────────────────────────────────────────────────────────────────────────┘
|
|
60
|
+
┌─ window.load ──────────────────────────────────────────────────────────────┐
|
|
61
|
+
│ AddShoppers referral widget (async) │
|
|
62
|
+
└────────────────────────────────────────────────────────────────────────────┘
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## 1. CSS tiering
|
|
68
|
+
|
|
69
|
+
### Critical bundle (render-blocking)
|
|
70
|
+
|
|
71
|
+
- **Source:** `_styles/critical.css` → `assets/critical.css`
|
|
72
|
+
- **Scope:** Header + homepage hero shell only; narrow `@source` list (~12 Liquid files)
|
|
73
|
+
- **Loaded in:** `snippets/_head-style.liquid` via `stylesheet_tag`
|
|
74
|
+
|
|
75
|
+
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.
|
|
76
|
+
|
|
77
|
+
### Full stylesheet (non-blocking)
|
|
78
|
+
|
|
79
|
+
- **Source:** `_styles/main.css` → `assets/style.css`
|
|
80
|
+
- **Pattern:** `media="print" onload="this.media='all'"` + `<noscript>` fallback
|
|
81
|
+
- **Also:** `rel="preload" as="style" fetchpriority="high"` for early discovery
|
|
82
|
+
|
|
83
|
+
Build: `npm run tailwind:build` or `tailwind:watch` (builds both critical + main).
|
|
84
|
+
|
|
85
|
+
### Theme tokens
|
|
86
|
+
|
|
87
|
+
- `_styles/theme-tokens.css` — shared `@theme` imported by both CSS entry points
|
|
88
|
+
- Inline `:root` variables in `_head-style.liquid` for fonts, spacing, buttons
|
|
89
|
+
|
|
90
|
+
### Disabled / deferred CSS ideas
|
|
91
|
+
|
|
92
|
+
- `content-visibility: auto` on sections — **commented out** in `_styles/main.css` (evaluate before enabling)
|
|
93
|
+
- Lazysizes CSS — removed; native `loading="lazy"` only
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 2. Font strategy
|
|
98
|
+
|
|
99
|
+
### Self-hosted fonts (no Typekit / Google Fonts on storefront)
|
|
100
|
+
|
|
101
|
+
| Family | File | Preload? | Usage |
|
|
102
|
+
|--------|------|----------|-------|
|
|
103
|
+
| Grosa Medium | `grosa-medium.woff2` | **Yes** | Above-the-fold body emphasis |
|
|
104
|
+
| Ivy Presto Headline Light | `ivypresto-headline-light.woff2` | **Yes** | Headings (`iheadline`) |
|
|
105
|
+
| Grosa Regular | `grosa-regular.woff2` | No | Body text; loads via `@font-face` |
|
|
106
|
+
|
|
107
|
+
All use `font-display: swap`.
|
|
108
|
+
|
|
109
|
+
### Font blocking
|
|
110
|
+
|
|
111
|
+
`_head-resource-blocker.liquid` + `layout/theme.liquid` sanitization block:
|
|
112
|
+
|
|
113
|
+
- Adobe Typekit (`use.typekit.net`, `p.typekit.net`)
|
|
114
|
+
- Google Fonts
|
|
115
|
+
- Shopify Font CDN webfonts (`fonts.shopifycdn.com`, Nunito)
|
|
116
|
+
- Klaviyo legacy brand fonts (`kl-custom-fonts`, Shopify Files `.woff`)
|
|
117
|
+
- Rebuy onsite CDN (`cdn.rebuyengine.com`, `/onsite/`) — **API** (`rebuyengine.com/api/*`) still allowed
|
|
118
|
+
|
|
119
|
+
### Preconnect budget
|
|
120
|
+
|
|
121
|
+
- `_head-typography.liquid`: `cdn.shopify.com`, `cdn.shopifycloud.com`; dns-prefetch `v.shopify.com`
|
|
122
|
+
- Unused preconnects removed: `fonts.shopifycdn.com`, `shop.app`
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## 3. JavaScript architecture
|
|
127
|
+
|
|
128
|
+
### Build system
|
|
129
|
+
|
|
130
|
+
**File:** `.climaybe/build-scripts.js` (via `npm run scripts:build`)
|
|
131
|
+
|
|
132
|
+
| Entry (`_scripts/`) | Output (`assets/`) | Loaded |
|
|
133
|
+
|---------------------|-------------------|--------|
|
|
134
|
+
| `main.js` | `index.js` | All pages, `<head>` module |
|
|
135
|
+
| `deferred.js` | `deferred.js` | End of `<body>` |
|
|
136
|
+
| `deferred-integrations.js` | `deferred-integrations.js` | Idle inject when DOM matches |
|
|
137
|
+
| `productpage.js` | `productpage.js` | PDP `<head>` |
|
|
138
|
+
| `product--variant-radios.js` | `product--variant-radios.js` | PDP `<head>` |
|
|
139
|
+
| `debug-proxy.js` | `debug-proxy.js` | Conditional `<head>` |
|
|
140
|
+
|
|
141
|
+
**Also in head (not in bundler — manual sync risk):**
|
|
142
|
+
|
|
143
|
+
- `collectionpage.js` ← `_scripts/collectionpage.js`
|
|
144
|
+
- `cart.js` ← `_scripts/cart.js`
|
|
145
|
+
|
|
146
|
+
**Per-section assets** (loaded with `defer` / `type="module"` from sections): `wishlist-feed.js`, `irl.js`, `reviews-custom.js`, `product--form.js`, `product-model.js`, `loading-banner.js`, etc.
|
|
147
|
+
|
|
148
|
+
Production build strips JSDoc and `console.*` from bundled output.
|
|
149
|
+
|
|
150
|
+
### `index.js` (critical bundle)
|
|
151
|
+
|
|
152
|
+
**Entry:** `_scripts/main.js`
|
|
153
|
+
|
|
154
|
+
Includes: `core-components.js`, `header.js`, `electric-section.js`, `electric-slider.js`, `electric-search.js`, `cart-dynamic.js`, `electric-cart-upsell-tabs.js`, pagination, checkout spinner delegation.
|
|
155
|
+
|
|
156
|
+
**Keep lean.** New features belong in `deferred.js`, page bundles, or lazy-loaded section scripts unless needed for first paint.
|
|
157
|
+
|
|
158
|
+
### `deferred.js` (body bundle)
|
|
159
|
+
|
|
160
|
+
**Entry:** `_scripts/deferred.js`
|
|
161
|
+
|
|
162
|
+
Always loads: product card scripts, quick ATC modal, Klaviyo cart tracking, Hotjar deferred, chat button visibility.
|
|
163
|
+
|
|
164
|
+
**Conditionally loads** `deferred-integrations.js` when DOM contains:
|
|
165
|
+
`electric-wish`, `electric-wish-counter`, `promo-banner`, `electric-rebuy-simplify`, `footer-newsletter`, `[data-gorgias-widget]`, `.js-promo-banner-text`
|
|
166
|
+
|
|
167
|
+
Uses `scheduleIdle(..., { timeout: 3000 })` from `_scripts/utils/perf.js`.
|
|
168
|
+
|
|
169
|
+
### `productpage.js` (PDP bundle)
|
|
170
|
+
|
|
171
|
+
Includes: gallery, video player, variant preview, variant prefetch, Rebuy product view, gift card sync.
|
|
172
|
+
|
|
173
|
+
### Idle scheduling utility
|
|
174
|
+
|
|
175
|
+
**Canonical:** `_scripts/utils/perf.js` → `scheduleIdle(callback, { timeout })`
|
|
176
|
+
|
|
177
|
+
Falls back to `setTimeout(1)` when `requestIdleCallback` unavailable.
|
|
178
|
+
|
|
179
|
+
**Consumers:** `deferred.js`, `hotjar-deferred.js`, `rebuy-product-view.js`, `product-variant-prefetch.js`, `recently-viewed.js`
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## 4. Third-party containment
|
|
184
|
+
|
|
185
|
+
### Layer 1: Resource blocker (runtime)
|
|
186
|
+
|
|
187
|
+
`snippets/_head-resource-blocker.liquid` — **must stay first in `<head>`**
|
|
188
|
+
|
|
189
|
+
Patches: `fetch`, `XHR`, `createElement`, `setAttribute`, DOM insertion, inline style mutation, `MutationObserver` for late injections.
|
|
190
|
+
|
|
191
|
+
### Layer 2: Header sanitization (Liquid)
|
|
192
|
+
|
|
193
|
+
`layout/theme.liquid` captures `content_for_header`, replaces blocked host strings with `blocked.invalid/*`, then runs a cleanup script.
|
|
194
|
+
|
|
195
|
+
### Layer 3: Deferred / conditional loading
|
|
196
|
+
|
|
197
|
+
| Service | File | Strategy |
|
|
198
|
+
|---------|------|----------|
|
|
199
|
+
| Hotjar | `_scripts/hotjar-deferred.js` | Idle 8s or first user interaction |
|
|
200
|
+
| Klaviyo cart events | `_scripts/klaviyo-cart-tracking.js` | `deferred.js`; listens `cart:added` |
|
|
201
|
+
| Rebuy analytics (PDP view) | `_scripts/rebuy-product-view.js` | Idle 2s on product pages |
|
|
202
|
+
| Rebuy recommendations | `_scripts/electric-rebuy-simplify.js` | Integrations bundle; IO `rootMargin: 1200px` |
|
|
203
|
+
| AddShoppers | `_head-script.liquid` | `window.load`, async, `loadCss: false` |
|
|
204
|
+
| Affirm | `affirm-messaging` web component | Lazy on first product form |
|
|
205
|
+
| Kimonix | `_body-script.liquid` | Async only if `kimonix_void_script` in header |
|
|
206
|
+
| Gorgias | App embed + `gorgias-widget.js` | App via Shopify; triggers deferred |
|
|
207
|
+
|
|
208
|
+
### Layer 4: Console filter (Lighthouse only)
|
|
209
|
+
|
|
210
|
+
`_head-console-filter.liquid` — suppresses known third-party `console.error/warn` patterns. **Do not rely on this for debugging** — disable mentally when investigating app bugs.
|
|
211
|
+
|
|
212
|
+
### Shopify app embeds (`config/settings_data.json`)
|
|
213
|
+
|
|
214
|
+
| App | Status | Notes |
|
|
215
|
+
|-----|--------|-------|
|
|
216
|
+
| Elevar (GTM/dataLayer) | Enabled | Primary tag orchestration — audit in GTM, not theme |
|
|
217
|
+
| Klaviyo onsite embed | Enabled | Fonts may be blocked; onsite JS from Shopify |
|
|
218
|
+
| Gorgias | Enabled | Chat |
|
|
219
|
+
| Photolock | Enabled | Image protection |
|
|
220
|
+
| Okendo, Checkout Blocks | Disabled | — |
|
|
221
|
+
|
|
222
|
+
### Inactive / dead integrations
|
|
223
|
+
|
|
224
|
+
| File | Status |
|
|
225
|
+
|------|--------|
|
|
226
|
+
| `snippets/_script-blocker.liquid` | Fully commented out |
|
|
227
|
+
| `snippets/_head-rebuy-stylesheet-blocker.liquid` | Not rendered |
|
|
228
|
+
| `snippets/_head-csp.liquid` | Not rendered |
|
|
229
|
+
| `snippets/_criteo-tracking.liquid` | Not rendered |
|
|
230
|
+
| `snippets/shoplift.liquid` | Commented out in `theme.liquid` |
|
|
231
|
+
| instant.page | Removed; `data-instant-allow-query-string` on body is legacy |
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## 5. Images & LCP
|
|
236
|
+
|
|
237
|
+
### Snippets
|
|
238
|
+
|
|
239
|
+
| Snippet | Behavior |
|
|
240
|
+
|---------|----------|
|
|
241
|
+
| `a--image.liquid` | Responsive `srcset`; LCP: `fetchpriority="high"`, `loading="eager"`, `decoding="async"`; else `loading="lazy"`; auto-lazy after 2nd section/item |
|
|
242
|
+
| `a--image-responsive.liquid` | `<picture>` breakpoints; LCP path avoids desktop 2x retina |
|
|
243
|
+
|
|
244
|
+
### Preloads
|
|
245
|
+
|
|
246
|
+
| Snippet | When | What |
|
|
247
|
+
|---------|------|------|
|
|
248
|
+
| `_index-preload-hero.liquid` | `request.page_type == 'index'` | Mobile 420w hero from `settings.homepage_lcp_image` |
|
|
249
|
+
| `_product-preload-slider-images.liquid` | PDP | Up to 5 portrait slider images, `imagesrcset` 480/960 |
|
|
250
|
+
| `_head-seo.liquid` | All | Favicons `fetchpriority="low"` |
|
|
251
|
+
|
|
252
|
+
### No lazysizes
|
|
253
|
+
|
|
254
|
+
Theme uses **native `loading="lazy"`** only. `unveilLazyloadIn()` in `core-components.js` is a no-op kept for API compatibility.
|
|
255
|
+
|
|
256
|
+
### Variant image prefetch (PDP)
|
|
257
|
+
|
|
258
|
+
`_scripts/product-variant-prefetch.js`:
|
|
259
|
+
|
|
260
|
+
- **Desktop:** hover/focus → fetch `?section_id=api--product-images&variant={id}` → preload image URLs from JSON payload
|
|
261
|
+
- **Touch:** after 5s idle, max **3** variants, images section only (no `product--main` fetch)
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## 6. Navigation & prefetch
|
|
266
|
+
|
|
267
|
+
### Speculation Rules (native prerender)
|
|
268
|
+
|
|
269
|
+
`snippets/_head-script.liquid` — `eagerness: "conservative"`
|
|
270
|
+
|
|
271
|
+
Prerenders same-origin links except account, cart, login. Do not add instant.page alongside this.
|
|
272
|
+
|
|
273
|
+
### electric-section (Section Rendering API)
|
|
274
|
+
|
|
275
|
+
`_scripts/electric-section.js`:
|
|
276
|
+
|
|
277
|
+
- Lazy load via `IntersectionObserver` (`data-onload`, configurable `data-onload-root-margin`)
|
|
278
|
+
- Fragment cache (max 10 entries)
|
|
279
|
+
- Events: `electric-section:prefetch`, `electric-section:fetch`
|
|
280
|
+
- Used for collection tabs, IRL, more-to-love, header fragments, etc.
|
|
281
|
+
|
|
282
|
+
### electric-pub (tab prefetch)
|
|
283
|
+
|
|
284
|
+
`_scripts/electric-pub.js` — prefetches tab content on hover/focus or intersection.
|
|
285
|
+
|
|
286
|
+
### Cart script on demand
|
|
287
|
+
|
|
288
|
+
`core-components.js` → `loadCartScriptOnce()` injects `cart.js` with `defer` when cart drawer opens (not on every page upfront).
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## 7. Shopify-specific patterns
|
|
293
|
+
|
|
294
|
+
### Route-conditional head scripts
|
|
295
|
+
|
|
296
|
+
From `_head-script.liquid`:
|
|
297
|
+
|
|
298
|
+
```liquid
|
|
299
|
+
index.js → all pages
|
|
300
|
+
productpage.js → product
|
|
301
|
+
product--variant-radios.js → product
|
|
302
|
+
collectionpage.js → collection, search
|
|
303
|
+
cart.js → cart template
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
### Geoblock
|
|
307
|
+
|
|
308
|
+
When `settings.geoblock_enabled`:
|
|
309
|
+
|
|
310
|
+
- `html.geoblock-pending` hides body until `/browsing_context_suggestions.json` returns
|
|
311
|
+
- Currently **disabled** in `settings_data.json`
|
|
312
|
+
- **Caveat:** fetch failure only warns — body can stay hidden if enabled without a fallback
|
|
313
|
+
|
|
314
|
+
### Fabric cart restoration
|
|
315
|
+
|
|
316
|
+
Inline in `_head-script.liquid` — cart/product template logic for `_fabric` localStorage flow.
|
|
317
|
+
|
|
318
|
+
### Debug API proxy
|
|
319
|
+
|
|
320
|
+
`_scripts/debug-proxy.js` — loads only when debug cookie, `?debug_proxy*`, or Shopify design mode. Rewrites proxy API fetch URLs.
|
|
321
|
+
|
|
322
|
+
---
|
|
323
|
+
|
|
324
|
+
## 8. Klaviyo & analytics data flow
|
|
325
|
+
|
|
326
|
+
### Cart tracking (deferred)
|
|
327
|
+
|
|
328
|
+
1. `product--form.js` dispatches `cart:added` with cart payload
|
|
329
|
+
2. `klaviyo-cart-tracking.js` waits for `_learnq`, pushes `Added to Cart v3` + legacy `Added to Cart`
|
|
330
|
+
3. Product page context from `window.theme.klaviyoCart` in `_script-variables.liquid`
|
|
331
|
+
4. Cart page replays `cart:added` from `sessionStorage cart:justAdded`
|
|
332
|
+
|
|
333
|
+
### Viewed Product (not deferred)
|
|
334
|
+
|
|
335
|
+
`sections/product--icons-model.liquid` — large inline Klaviyo script when comparison section renders. **Candidate for future deferral.**
|
|
336
|
+
|
|
337
|
+
### Rebuy
|
|
338
|
+
|
|
339
|
+
- Widget CDN blocked; custom `electric-rebuy-simplify` uses API
|
|
340
|
+
- Product view POST deferred via `rebuy-product-view.js`
|
|
341
|
+
- Global helpers in `_script-variables.liquid` (`rebuyTrackEvent`, session storage for added variants)
|
|
342
|
+
|
|
343
|
+
---
|
|
344
|
+
|
|
345
|
+
## 9. Adding new features — checklist
|
|
346
|
+
|
|
347
|
+
### New JavaScript
|
|
348
|
+
|
|
349
|
+
- [ ] Default to `_scripts/` source file, not `assets/`
|
|
350
|
+
- [ ] If needed on every page → consider `deferred.js` not `main.js`
|
|
351
|
+
- [ ] If third-party → defer (idle/interaction/load), never sync in head unless unavoidable
|
|
352
|
+
- [ ] If PDP-only → `productpage.js` or section `{% javascript %}`
|
|
353
|
+
- [ ] Add to `.climaybe/build-scripts.js` if new bundle entry
|
|
354
|
+
- [ ] Run `npm run scripts:build`
|
|
355
|
+
- [ ] Use `scheduleIdle` from `utils/perf.js` for non-critical init
|
|
356
|
+
- [ ] AbortController + cleanup in web components
|
|
357
|
+
|
|
358
|
+
### New third-party script
|
|
359
|
+
|
|
360
|
+
- [ ] Can it go through GTM with consent + idle trigger instead of theme?
|
|
361
|
+
- [ ] If app embed: expect `content_for_header` injection — add to blocker list if it conflicts (fonts, duplicate widgets)
|
|
362
|
+
- [ ] Add domain to `_head-console-filter` only if noise is unavoidable
|
|
363
|
+
- [ ] Never add sync analytics in `_head-script.liquid`
|
|
364
|
+
|
|
365
|
+
### New above-the-fold UI
|
|
366
|
+
|
|
367
|
+
- [ ] Extend `critical.css` `@source` if new classes needed at first paint
|
|
368
|
+
- [ ] LCP image: use `fetchpriority="high"`, explicit dimensions, preload in dedicated snippet
|
|
369
|
+
- [ ] Do not preload more than 2 fonts
|
|
370
|
+
|
|
371
|
+
### New section below fold
|
|
372
|
+
|
|
373
|
+
- [ ] `loading="lazy"` on images
|
|
374
|
+
- [ ] Consider `<electric-section data-onload>` instead of bundling in `index.js`
|
|
375
|
+
- [ ] Pass `lazyload: true` to product cards
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
379
|
+
## 10. Testing & measurement
|
|
380
|
+
|
|
381
|
+
### Before shipping perf changes
|
|
382
|
+
|
|
383
|
+
1. **Chrome DevTools** — Performance trace: LCP element, long tasks, third-party cost
|
|
384
|
+
2. **Network** — throttle Slow 4G; verify critical.css → first paint, style.css non-blocking
|
|
385
|
+
3. **Coverage** — how much of `index.js` executes on homepage vs PDP
|
|
386
|
+
4. **Block third-parties test** — block `googletagmanager.com`, `static.klaviyo.com`, `static.hotjar.com`; if TBT collapses, marketing stack is the bottleneck
|
|
387
|
+
5. **Theme Check** — `npm run lint:liquid`
|
|
388
|
+
6. **Build** — `npm run scripts:build && npm run tailwind:build`
|
|
389
|
+
|
|
390
|
+
### Debug modes
|
|
391
|
+
|
|
392
|
+
| URL param | Effect |
|
|
393
|
+
|-----------|--------|
|
|
394
|
+
| `?debug_typekit=1` | Typekit audit (`_head-typekit-debug`) |
|
|
395
|
+
| `?debug_rebuy=1` | Rebuy logging |
|
|
396
|
+
| `?debug_proxy=1` | API proxy prompt |
|
|
397
|
+
| `?debug_proxy_domain=` | Set proxy origin |
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## 11. Known gaps & maintenance risks
|
|
402
|
+
|
|
403
|
+
1. **`collectionpage.js` / `cart.js` not in build targets** — `_scripts` edits may not reach `assets/` until manual copy or build update
|
|
404
|
+
2. **Many section scripts outside bundler** — verify `assets/` sync when editing `_scripts/wishlist-feed.js`, etc.
|
|
405
|
+
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
|
|
406
|
+
4. **`index.js` size (~340KB+)** — largest theme-controlled bottleneck; split `core-components.js` further if TBT regresses
|
|
407
|
+
5. **GTM / Elevar** — largest real-world cost; theme cannot fix container bloat
|
|
408
|
+
6. **`_head-console-filter`** — masks errors; misleading during app debugging
|
|
409
|
+
7. **Klaviyo Viewed Product inline** — still heavy on PDP with icons model section
|
|
410
|
+
|
|
411
|
+
---
|
|
412
|
+
|
|
413
|
+
## 12. File quick reference
|
|
414
|
+
|
|
415
|
+
| Concern | Primary files |
|
|
416
|
+
|---------|---------------|
|
|
417
|
+
| Load order | `layout/theme.liquid` |
|
|
418
|
+
| Resource blocking | `snippets/_head-resource-blocker.liquid` |
|
|
419
|
+
| CSS tiering | `snippets/_head-style.liquid`, `_styles/critical.css`, `_styles/main.css` |
|
|
420
|
+
| JS bootstrap | `snippets/_head-script.liquid`, `snippets/_body-script.liquid` |
|
|
421
|
+
| Globals | `snippets/_script-variables.liquid` |
|
|
422
|
+
| Build | `.climaybe/build-scripts.js`, `package.json` |
|
|
423
|
+
| Idle utils | `_scripts/utils/perf.js` |
|
|
424
|
+
| Images | `snippets/a--image.liquid`, `snippets/a--image-responsive.liquid` |
|
|
425
|
+
| LCP preloads | `snippets/_index-preload-hero.liquid`, `snippets/_product-preload-slider-images.liquid` |
|
|
426
|
+
| Section lazy load | `_scripts/electric-section.js` |
|
|
427
|
+
| Deferred 3P | `_scripts/hotjar-deferred.js`, `_scripts/klaviyo-cart-tracking.js`, `_scripts/rebuy-product-view.js` |
|
|
428
|
+
| App embeds | `config/settings_data.json` |
|
|
429
|
+
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
## 13. Related rules
|
|
433
|
+
|
|
434
|
+
- `javascript-standards.mdc` — web components, layout thrashing, `scheduleIdle` patterns
|
|
435
|
+
- `tailwindcss-rules.mdc` — static classes, `@source` for critical CSS
|
|
436
|
+
- `project-overview.mdc` — performance targets (< 16ms init, 60fps), build outputs vs source (`_scripts/` / `_styles/`, never `assets/` directly)
|