Performance

FilterIQ is engineered for minimal performance impact on your storefront. This page covers bundle sizes, loading strategy, and how we prevent layout shifts.

Bundle Sizes

The Theme App Extension loads these assets on your storefront:

Asset	Size (gzip)	Loading	Purpose
`ssf-critical-layout.css`	~2KB	Synchronous	Reserves sidebar space, prevents CLS
`search-filter.css`	~3KB	Synchronous	Core filter and search styling
`search-filter.js`	~15KB	Deferred	Core initialization, grid detection, filter rendering
`instant-search.js`	~8KB	Deferred	Search dropdown widget
`instant-search.css`	~1KB	Async	Search dropdown styling
`mobile-drawer.js`	~4KB	Deferred	Mobile drawer behavior
`mobile-drawer.css`	~1KB	Async	Mobile drawer styling
`analytics-client.js`	~3KB	Deferred	Event tracking
`accessibility.js`	~2KB	Deferred	WCAG enhancements
`accessibility.css`	~0.5KB	Async	Focus styles, screen reader utilities

Total JavaScript: ~32KB gzipped Total CSS: ~7.5KB gzipped

Comparison

App	JS Bundle	CSS Bundle
FilterIQ	~32KB	~7.5KB
Industry average (search apps)	~80-120KB	~15-25KB

Loading Strategy

CSS Loading

CSS is loaded in two tiers:

Critical CSS (ssf-critical-layout.css, search-filter.css) -- Loaded synchronously via stylesheet_tag. These are render-blocking but essential for preventing CLS. Combined size is under 5KB.
Enhancement CSS (instant-search.css, mobile-drawer.css, accessibility.css) -- Loaded asynchronously using the preload/onload pattern. These do not block rendering.

JavaScript Loading

All JavaScript files use the defer attribute, meaning they:

Download in parallel with HTML parsing
Execute after the DOM is ready
Do not block rendering

The execution order is:

search-filter.js -- Core initialization and grid detection
instant-search.js -- Search dropdown setup
mobile-drawer.js -- Mobile drawer setup (only initializes on mobile viewports)
analytics-client.js -- Event tracking
accessibility.js -- WCAG enhancements

Font Loading

The app loads Inter from Google Fonts with display=swap, ensuring text renders immediately with a system font fallback and swaps to Inter when it finishes loading.

CLS Prevention

Cumulative Layout Shift (CLS) is a Core Web Vital that measures visual stability. Adding a filter sidebar to a collection page can cause significant CLS if not handled carefully.

Our CLS Strategy

Inline CLS guard -- The very first thing the embed executes is an inline script that adds a ssf-loading class to <body> and injects a style that hides the product grid container with visibility: hidden. This happens before any external CSS or JS downloads.
Critical layout CSS -- Loaded synchronously, this CSS reserves the exact width the filter sidebar will occupy. The browser allocates space for the sidebar on its first paint.
DOM surgery -- The core JS moves the product grid into a flex container alongside the filter sidebar. Because the grid is hidden during this operation, there is no visible shift.
Reveal -- After DOM surgery is complete, the ssf-loading class is removed and the grid becomes visible in its final position. The entire sequence happens before the user perceives any layout change.

CLS Telemetry

The app includes a CLS telemetry module (ssf-cls-telemetry.js) that measures actual CLS values on your storefront and reports them back to the analytics service. You can monitor CLS impact in Analytics > Performance.

API Performance

Operation	Target	Typical
Search query (storefront)	< 50ms	20-40ms
Autocomplete suggestion	< 30ms	10-25ms
Filter facet calculation	< 20ms	5-15ms
Analytics event ingest	< 100ms	30-60ms
Product webhook processing	< 1s	200-500ms

Caching

Widget config -- Cached in-memory on the backend for 60 seconds per shop
Search results -- Cached server-side for fast repeat queries
Filter configuration -- Baked into a Shopify metafield (zero-latency storefront reads)

Lighthouse Impact

When properly configured, FilterIQ typically has the following impact on Lighthouse scores:

Metric	Impact
LCP (Largest Contentful Paint)	Negligible (deferred loading)
FID (First Input Delay)	Negligible (non-blocking JS)
CLS (Cumulative Layout Shift)	Zero (CLS guard system)
Performance Score	-0 to -2 points typical

Optimizing Performance

For fastest loading

Ensure your theme's <head> does not have excessive render-blocking resources
Enable HTTP/2 on your domain (Shopify does this by default)
Use a CDN for custom assets (Shopify CDN handles app extension assets automatically)

For best CLS scores

Keep the Theme App Extension embed enabled (do not toggle it on and off)
Do not add custom CSS that overrides the ssf-loading class behavior
Avoid custom JavaScript that manipulates the product grid DOM before the app initializes