CDN and Images

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 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 /> 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:

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:

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

See Best practices for more about urlTemplate and sizes.

Use store assets uploaded with WebDAV

Two helper functions in lib/store-assets 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:

<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 />:

<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:

<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 />:

<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:

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

Best practices

Set sizes

Wherever you can, use the sizes prop of <Image /> to describe how the image’s size varies with the viewport:

<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:

query GetProduct(
  $productId: Int!
) {
  site {
    product(entityId: $productId) {
      defaultImage {
        url(width: 700)
      }
    }
  }
}

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

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):

query GetProduct(
  $productId: Int!
) {
  site {
    product(entityId: $productId) {
      defaultImage {
        urlTemplate
      }
    }
  }
}

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

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.