// utils/script-scheduler.ts
interface ScriptConfig {
  id: string;
  src: string;
  deferUntil?: 'idle' | 'interaction' | 'load';
  callback?: () => void;
}

export function scheduleScript(config: ScriptConfig): void {
  const { id, src, deferUntil = 'idle', callback } = config;
  
  if (document.getElementById(id)) return; // Prevent duplicate injection

  const script = document.createElement('script');
  script.id = id;
  script.src = src;
  script.async = true;

  const execute = () => {
    document.head.appendChild(script);
    if (callback) callback();
  };

  switch (deferUntil) {
    case 'idle':
      if ('requestIdleCallback' in window) {
        requestIdleCallback(execute, { timeout: 2000 });
      } else {
        setTimeout(execute, 2000);
      }
      break;
    case 'interaction':
      const trigger = () => {
        execute();
        window.removeEventListener('scroll', trigger);
        window.removeEventListener('click', trigger);
      };
      window.addEventListener('scroll', trigger, { once: true });
      window.addEventListener('click', trigger, { once: true });
      break;
    case 'load':
      window.addEventListener('load', execute, { once: true });
      break;
    default:
      execute();
  }
}

<script>
  window.ScriptScheduler.scheduleScript({
    id: 'review-widget-init',
    src: 'https://cdn.reviews.app/widget.js',
    deferUntil: 'idle'
  });
</script>

xplicit hints, it assigns default priority. The fix requires three coordinated directives: eager loading, high fetch priority, and a preload link.

Liquid implementation for hero sections:

{%- assign hero_image = section.settings.hero_image | default: placeholder_image -%}
{%- assign display_width = 1400 -%}

<link 
  rel="preload" 
  as="image" 
  href="{{ hero_image | image_url: width: display_width }}" 
  fetchpriority="high"
>

<img 
  src="{{ hero_image | image_url: width: display_width }}" 
  alt="{{ section.settings.hero_alt | escape }}"
  width="{{ display_width }}"
  height="{{ hero_image.height | times: display_width | divided_by: hero_image.width }}"
  loading="eager"
  fetchpriority="high"
  decoding="async"
>

Architecture Rationale: loading="eager" overrides lazy-loading defaults for the critical element. fetchpriority="high" signals the browser to allocate maximum network bandwidth to this resource. The <link rel="preload"> tag ensures the preload scanner discovers the image before HTML parsing reaches the <img> tag. Specifying explicit width and height prevents layout shift and allows the browser to allocate space immediately. This combination typically reduces LCP by 600–1,200ms on Dawn-based themes.

Step 4: Optimize Liquid Render Time

Server-side template rendering occurs before the browser receives HTML. Complex Liquid logic increases Time to First Byte (TTFB), which directly impacts LCP. Common anti-patterns include nested loops over all_products, unbounded metafield iteration, and redundant snippet rendering.

Implement section-level caching to avoid repeated computation:

{% comment %} sections/product-grid.liquid {% endcomment %}
{% assign cached_products = section.settings.products | default: collections.all.products %}
{% assign product_limit = section.settings.grid_limit | default: 12 %}

{% if cached_products.size > 0 %}
  {% for product in cached_products limit: product_limit %}
    {% render 'product-card', product: product, show_vendor: true %}
  {% endfor %}
{% else %}
  {% render 'empty-state', message: 'No products available' %}
{% endif %}

{% schema %}
{
  "name": "Product Grid",
  "settings": [
    {
      "type": "product_list",
      "id": "products",
      "label": "Select Products"
    },
    {
      "type": "range",
      "id": "grid_limit",
      "min": 4,
      "max": 48,
      "step": 4,
      "default": 12,
      "label": "Products per Row"
    }
  ]
}
{% endschema %}

Architecture Rationale: Limiting iterations with limit prevents unbounded rendering. Using product_list schema settings allows merchants to curate collections without querying global all_products, which bypasses Shopify's internal caching and triggers full collection scans. Pre-calculating limits and avoiding nested loops reduces Liquid execution time by 30–60%.

Step 5: Streamline Font Delivery

Custom typography introduces additional network requests and render-blocking behavior. The optimal strategy is self-hosting, character subsetting, and explicit display behavior.

Upload font files to assets/ and reference them directly:

/* assets/custom-typography.css */
@font-face {
  font-family: 'StoreDisplay';
  src: url('{{ "store-display.woff2" | asset_url }}') format('woff2');
  font-weight: 400 700;
  font-style: normal;
  font-display: swap;
}

body {
  font-family: 'StoreDisplay', system-ui, -apple-system, sans-serif;
}

Architecture Rationale: font-display: swap ensures text remains visible during font download, preventing invisible text flashes. WOFF2 format provides optimal compression. Self-hosting eliminates third-party font CDN latency and allows Shopify's asset pipeline to handle caching headers automatically. Subsetting to required character ranges (e.g., Latin, numerals, punctuation) reduces file size by 40–70%.

Pitfall Guide

1. The Compression Mirage

Explanation: Focusing exclusively on image file size while ignoring execution order. Compressed images still load late if blocked by synchronous scripts or deprioritized by the browser. Fix: Audit the critical rendering path first. Apply compression only after script deferral and LCP prioritization are implemented.

2. Synchronous App Injection

Explanation: Third-party applications load via <script src="..."></script> without async or defer, halting HTML parsing until execution completes. Fix: Wrap all non-essential app scripts in the idle scheduler pattern. Verify functionality after deferral; most modern apps support asynchronous initialization.

3. Unbounded Collection Iteration

Explanation: Using {% for product in all_products %} without limits forces Shopify to scan the entire product catalog during render, increasing TTFB and memory usage. Fix: Replace with curated collections or schema-driven product lists. Always apply limit filters and paginate for large datasets.

4. Preload Overload

Explanation: Adding <link rel="preload"> to multiple resources dilutes browser priority signals. The preload scanner treats all preloaded assets as high priority, causing resource contention. Fix: Preload only the exact LCP candidate. Use fetchpriority="high" on the element itself instead of preloading secondary assets.

5. Font Format Neglect

Explanation: Serving TTF or OTF files without WOFF2 conversion, or omitting font-display: swap, causes render-blocking behavior and text invisibility. Fix: Convert all fonts to WOFF2. Always include font-display: swap. Self-host fonts to leverage Shopify's CDN and avoid external DNS lookups.

6. Optimization App Paradox

Explanation: Installing "speed optimization" applications that inject additional JavaScript to manage other scripts. This creates a recursive dependency chain that increases main thread work. Fix: Remove optimization apps. Implement script scheduling natively in theme code. The fix is almost always removal, not addition.

7. Missing Dimension Attributes

Explanation: Omitting width and height on images forces the browser to reflow layout once dimensions are discovered, triggering Cumulative Layout Shift (CLS) and delaying paint. Fix: Calculate aspect ratio in Liquid and pass explicit dimensions to <img> tags. Use responsive srcset only after fixed dimensions are established.

Production Bundle

Action Checklist

• Run PSI and WebPageTest to identify the exact LCP element and render-blocking resources
• Audit theme.liquid for synchronous <script> tags from third-party apps
• Implement idle/interaction-based script scheduling for non-critical JavaScript
• Add loading="eager", fetchpriority="high", and <link rel="preload"> to the hero image
• Replace all_products loops with schema-driven, limited collections
• Self-host typography files in WOFF2 format with font-display: swap
• Verify explicit width and height attributes on all above-the-fold images
• Re-run diagnostics to confirm LCP < 2.5s and CLS < 0.1

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Store with 5+ review/chat apps	Defer all non-critical scripts via idle scheduler	Eliminates render-blocking behavior without breaking functionality	Low (theme code modification only)
Hero image LCP > 3s on Dawn	Add preload + fetchpriority + eager loading	Directs browser to prioritize the actual LCP candidate	Low (template update)
TTFB > 800ms on collection pages	Replace all_products with curated schema lists	Reduces Liquid render time and server memory allocation	Medium (requires merchant curation)
Font flash or layout shift	Self-host WOFF2 + font-display: swap	Prevents render-blocking and ensures immediate text visibility	Low (asset upload + CSS update)
Considering "speed optimization" app	Reject and implement native scheduling	Apps add script weight; native code is lighter and more controllable	High (avoids subscription + performance debt)

Configuration Template

Copy this structure into your theme's asset pipeline for immediate deployment:

{%- comment -%} snippets/lcp-hero.liquid {%- endcomment -%}
{% assign hero_src = hero_image | image_url: width: 1400 %}
{% assign hero_width = 1400 %}
{% assign hero_height = hero_image.height | times: hero_width | divided_by: hero_image.width %}

<link rel="preload" as="image" href="{{ hero_src }}" fetchpriority="high">

<img 
  src="{{ hero_src }}" 
  alt="{{ hero_alt | escape }}"
  width="{{ hero_width }}"
  height="{{ hero_height }}"
  loading="eager"
  fetchpriority="high"
  decoding="async"
  class="hero__image"
>

// assets/script-scheduler.js
window.ScriptScheduler = {
  schedule: function(config) {
    if (document.getElementById(config.id)) return;
    const script = document.createElement('script');
    script.id = config.id;
    script.src = config.src;
    script.async = true;

    const run = () => document.head.appendChild(script);
    
    if (config.deferUntil === 'idle' && 'requestIdleCallback' in window) {
      requestIdleCallback(run, { timeout: 2000 });
    } else if (config.deferUntil === 'interaction') {
      const trigger = () => { run(); window.removeEventListener('scroll', trigger); };
      window.addEventListener('scroll', trigger, { once: true });
    } else {
      run();
    }
  }
};

Quick Start Guide

1. Capture Baseline: Run your homepage through WebPageTest. Note the LCP element and identify the top 3 render-blocking scripts.
2. Defer Scripts: Wrap each blocking script in the ScriptScheduler.schedule() call with deferUntil: 'idle'. Save and publish.
3. Prioritize Hero: Locate the hero image in your theme code. Add loading="eager", fetchpriority="high", and the <link rel="preload"> tag.
4. Verify: Re-run WebPageTest. Confirm LCP drops below 2.5s and main thread blocking time decreases by at least 40%.
5. Iterate: Address Liquid render bottlenecks and font delivery only if LCP remains above threshold after steps 1–4.