> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# CDN and Images

> How Catalyst handles image optimization and CDN delivery, using the Next.js Image component alongside BigCommerce's CDN.

Catalyst renders BigCommerce images through the BigCommerce CDN instead of your host's image optimization, which avoids image transformation costs on your hosting provider. This page explains how the Catalyst `<Image />` component works and how to build CDN URLs for catalog images, WebDAV assets, and Image Manager images.

## Images in Next.js

Next.js includes an [Image component](https://nextjs.org/docs/app/api-reference/components/image) that provides automatic optimization for rendering images. This component includes features like automatic generation of a `srcset` for responsive images, as well as lazy loading behavior.

Images rendered with this component are proxied through your own Next.js application, which transforms them. **Depending on your hosting provider, you may pay for those image transformations.**

## The Catalyst Image component

For loading images from the BigCommerce platform, Catalyst provides [`<Image />`](https://github.com/bigcommerce/catalyst/blob/canary/core/components/image/index.tsx) as a wrapper for Next's `<Image />` component to allow you to use BigCommerce CDN URLs directly.

The BigCommerce CDN already transforms images, so this component skips the Next.js transformation step. That reduces load on your application and removes the related hosting costs, with the same syntax as the Next.js component. For images that don't come from the BigCommerce CDN, it falls back to the default Next.js image loader.

Import it from `~/components/image`:

```tsx showLineNumbers={false}
import { Image } from '~/components/image';
```

## GraphQL-sourced image URLs

By default, `<Image />` is used to render many images from BigCommerce data loaded via the GraphQL Storefront API.

These image URLs, such as one queried from a product's `defaultImage` field, are BigCommerce CDN URLs, so `<Image />` loads them directly:

```tsx showLineNumbers={false}
<Image
    alt={product.name}
    src={product.defaultImage.urlTemplate}
    sizes="(min-width: 42rem) 50vw, 100vw"
/>
```

See [Best practices](#best-practices) for more about `urlTemplate` and `sizes`.

## Use store assets uploaded with WebDAV

Two helper functions in [`lib/store-assets`](https://github.com/bigcommerce/catalyst/blob/canary/core/lib/store-assets.ts) build URLs for assets in your store's WebDAV storage.

`contentAssetUrl()` builds a URL to any file in the `/content/` folder in your store's WebDAV storage. This link points to a PDF:

```tsx showLineNumbers={false}
<Link href={contentAssetUrl('pdfs/user-manual.pdf')} >
   User Manual
</Link>
```

For images uploaded to `/content`, `contentImageUrl()` builds a resizable image URL to use with `<Image />`:

```tsx showLineNumbers={false}
<Image
    alt="an assortment of brandless products against a blank background"
    src={contentImageUrl('newsletter-images/april.png')}
/>
```

To request a specific size, pass a size parameter of the form `123w`, `123x123`, or `original`:

```tsx showLineNumbers={false}
<Image
    src={contentImageUrl('newsletter-images/april.png', '1000w')}
/>
```

## Use images uploaded to Image Manager

`imageManagerImageUrl()` builds a CDN URL for an image uploaded to Image Manager. It returns a resizable URL template to use with `<Image />`:

```tsx showLineNumbers={false}
<Image
    alt="an assortment of brandless products against a blank background"
    src={imageManagerImageUrl('slideshow-bg-01.jpg')}
/>
```

To request a specific size, pass a size parameter of the form `123w`, `123x123`, or `original`:

```tsx showLineNumbers={false}
<Image
    src={imageManagerImageUrl('slideshow-bg-01.jpg', '1000w')}
/>
```

## Best practices

### Set `sizes`

Wherever you can, use the [`sizes`](https://nextjs.org/docs/app/api-reference/components/image#sizes) prop of `<Image />` to describe how the image's size varies with the viewport:

```tsx showLineNumbers={false}
<Image src={product.defaultImage.urlTemplate}
  sizes="(min-width: 42rem) 50vw, 100vw" />
```

From `sizes`, the component generates a `srcset` of CDN URLs, so the browser loads the resolution that fits the shopper's screen.

### Query `urlTemplate`

When fetching image URLs using the GraphQL Storefront API, a typical `url` field takes `width` (and optionally `height`) as an argument:

```graphql showLineNumbers={false}
query GetProduct(
  $productId: Int!
) {
  site {
    product(entityId: $productId) {
      defaultImage {
        url(width: 700)
      }
    }
  }
}
```

With a size specified, the returned URL looks like this:

```text showLineNumbers={false}
https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/700w/image.png
```

This CDN URL works with `<Image />`, but to get responsive images, query the `urlTemplate` field instead (available on the GraphQL [Image type](/developer/api-reference/graphql/storefront#definition-Image)):

```graphql showLineNumbers={false}
query GetProduct(
  $productId: Int!
) {
  site {
    product(entityId: $productId) {
      defaultImage {
        urlTemplate
      }
    }
  }
}
```

The returned URL has a size placeholder instead of a fixed size:

```text showLineNumbers={false}
https://cdn11.bigcommerce.com/s-{store_hash}/images/stencil/{:size}/image.png
```

`<Image />` uses this URL template to generate a `srcset` of CDN URLs that matches your `sizes` configuration.