> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Performance

> Optimization techniques for faster Layers SDK search and browse experiences, including prefetching, request deduplication, caching, and bundle size tips.

## Concurrent requests

Execute independent requests in parallel:

```typescript theme={null}
// ❌ Slow - sequential
const searchResult = await client.search({ query: 'ring' }).execute()
const collectionResult = await client.collection({ handle: 'featured' }).execute()

// ✅ Fast - parallel
const [searchResult, collectionResult] = await Promise.all([
  client.search({ query: 'ring' }).execute(),
  client.collection({ handle: 'featured' }).execute(),
])
```

Call prepare and autocomplete concurrently for search-as-you-type:

```typescript theme={null}
const search = client.search()
const suggest = client.suggest()

await Promise.all([
  search.prepare({ query: 'ring' }),
  suggest.execute('ring'),
])
```

## Prefetch next page

Prefetch the next page while the customer views the current page:

```typescript theme={null}
const collection = client.collection({ handle: 'shirts' })

// Load current page
const page1 = await collection.execute({ page: 1 })

// Prefetch next page in background
collection.execute({ page: 2 })
```

## Request only needed attributes

Reduce response size by requesting only required attributes:

```typescript theme={null}
// Configure attributes at client init time
const { data: client } = createClient({
  token: 'your-token',
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  attributes: ['price_range', 'body_html'], // additional attributes beyond defaults
})
```

## Debouncing

The SDK handles debouncing automatically, but you can tune it:

```typescript theme={null}
// Faster response (more API calls)
const suggest = client.suggest({ debounce: 150 })

// Slower response (fewer API calls)
const suggest = client.suggest({ debounce: 500 })
```

## Warm cache on page load

Preload common queries on page load:

```typescript theme={null}
Promise.all([
  client.search({ query: 'ring' }).prepare(),
  client.collection({ handle: 'featured' }).execute(),
])
```

## Early hints (Link header preloading)

Layers API responses automatically include HTTP `Link` headers with `rel="preload"` directives for product images in search and browse results. These headers enable browsers and CDNs to begin fetching images before your application processes the JSON response, reducing perceived load time.

### How it works

When a search or browse request returns results, the response includes a `Link` header with preload hints. These cover the `featured_media` images of the first results (up to 6 items). Each hint includes a responsive `imagesrcset` with multiple sizes so the browser can select the optimal resolution.

**Example response header:**

```
Link: <https://yourstore.com/cdn/shop/files/product.jpg>; rel="preload"; fetchpriority="high"; as="image"; imagesrcset="https://yourstore.com/cdn/shop/files/product.jpg?width=360 360w, https://yourstore.com/cdn/shop/files/product.jpg?width=540 540w, https://yourstore.com/cdn/shop/files/product.jpg?width=720 720w"; type="image/jpeg"
```

### Default behavior

* **Enabled by default** for all stores
* Covers the first 6 product images in the response
* The SDK rewrites image URLs to use your storefront domain (derived from the request `Referer` header) instead of the Shopify CDN domain. This improves cache hit rates when your storefront proxies images
* Generates responsive srcset entries at standard breakpoints (360, 540, 720, 900, 1080 pixels)

### Customization

You can configure early hints behavior per store through the Layers dashboard. Available options include:

| Option             | Description                                                            | Default           |
| :----------------- | :--------------------------------------------------------------------- | :---------------- |
| **Enabled**        | Toggle early hints on or off                                           | `true`            |
| **Srcset sizes**   | Custom responsive image widths (in pixels)                             | Platform defaults |
| **Rewrite domain** | A specific domain to use for image URLs instead of the referrer domain | Referrer domain   |
| **Rewrite URLs**   | Whether to rewrite Shopify CDN URLs to your storefront domain          | `true`            |

### Per-request overrides

You can override the default preload behavior on individual search and browse requests with the `responseOptions.mediaPreloads` body parameter. This is useful when:

* A specific page (such as a server-rendered template or a back-office tool) does not benefit from preload hints and you want to skip the extra `Link` header.
* Your client only renders specific image breakpoints and you want the emitted `imagesrcset` to match exactly, avoiding wasted preloads.

```json theme={null}
{
  "responseOptions": {
    "mediaPreloads": {
      "enabled": true,
      "srcsetSizes": [320, 640, 960]
    }
  }
}
```

**Behavior:**

* `enabled: false` skips the `Link` header for this request only.
* `enabled: true` cannot turn preloads on when they are disabled at the store level — store settings always take precedence.
* `srcsetSizes` accepts integers between `1` and `10000`. When provided, it overrides the store-level srcset configuration for this request only. Omit it to fall back to the store configuration or platform defaults.
* When preloads are emitted, the response body's `_meta.mediaPreloads.srcsetSizes` echoes the breakpoints that were used so you can verify the override took effect.

Per-request overrides are supported on the Text Search, Browse, Image Search, Similar Products, and Blocks endpoints.

## Next steps

<CardGroup cols={2}>
  <Card title="Caching" icon="database" href="/sdk/caching">
    Deep dive into SDK caching behavior.
  </Card>

  <Card title="Best Practices" icon="circle-check" href="/sdk/best-practices">
    Review SDK best practices and common pitfalls.
  </Card>
</CardGroup>