BizzPocket

Images and performance

On this page

Pictures are most of a storefront page's weight, and the hero picture usually decides how fast the page feels. This page shows how <Image> and responsiveImage() pick the right size from the BizzPocket CDN, how to write sizes, how to load the main picture first, how to keep the layout from jumping, and how to read the build's size report against a performance budget.


<Image>

<Image> from @bizzpocket/theme is a plain <img> with the defaults a storefront wants:

tsx
<Image src={p.image.src} alt={p.image.alt} width={400} height={400} sizes="(min-width: 768px) 25vw, 50vw" />
Prop What it does
src The picture. Only https: or a path that starts with a single / is allowed. Anything else renders nothing.
alt Required. Describe the picture, or pass '' when it is decoration.
width, height The picture's size in pixels. The browser uses them to reserve the space before the picture loads.
sizes How wide the picture is on screen. See Choosing sizes.
priority The page's main picture: load it at once, with high priority. See Priority and LCP.
widths Your own candidate widths. On the CDN, the largest one caps the ladder.
srcSet Your own srcset, passed through untouched. srcSet="" turns the automatic one off.
className A class for your CSS.

By default the picture loads lazily (loading="lazy", decoding="async"): the browser fetches it only when it comes near the screen. With priority it is loading="eager" and fetchpriority="high".

When src is a BizzPocket CDN or Unsplash picture, <Image> also adds a srcset and sizes, so a phone downloads a phone-sized file. It then changes src to a middle-sized candidate (the widest one up to 960 pixels), so a browser that ignores srcset, or a crawler, never pulls the largest file. width and height stay as you gave them. Any other host gets no srcset, and src is used as it is.

responsiveImage()

For a plain <img> (or when you need the attributes yourself, for example for SIR's variant table), spread responsiveImage({ src, sizes }) onto it:

tsx
<img {...responsiveImage({ src: photo.src, sizes: '100vw' })} alt="" width={1600} height={900} />

It returns { src, srcSet?, sizes? } and never throws. Unknown hosts, signed CDN links and malformed input come back as { src }. It is safe on the server and in islands. Check the URL first when it comes from data rather than a field: isSafeMediaUrl(src) (see data.md).

Input What you get
src the picture's URL
sizes required. Without it you get { src } back.
maxWidth the largest width worth offering for this slot
widths candidate widths for Unsplash (default 320, 480, 640, 828, 1080, 1280, 1600)

How the CDN ladder works

A picture a seller uploads is stored on the BizzPocket CDN at /v1/img/<store>/<id>. The CDN serves it at seven widths only, the "ladder":

160, 320, 480, 640, 960, 1280, 1600 pixels.

Each width has its own URL, with the format in its name: /v1/img/<store>/<id>/640.webp. Because the URL names the exact file, the CDN and every cache in between can keep it, and a phone and a desktop never get each other's file.

  • 1600 is the top. The CDN never makes a picture larger than the original or larger than 1600 px.
  • A width that is not on the ladder is redirected. /700.webp answers 308 to /960.webp: the width is rounded up, so a slot never gets fewer pixels than it asked for. The redirect costs the shopper one extra round trip, which is why the helpers only ever write ladder widths.
  • Formats. webp, avif, jpeg and png. The helpers keep the format the src had, and use webp when it had none.

So for a CDN picture, responsiveImage() writes one candidate per rung:

ts
responsiveImage({ src: '/v1/img/acme/3f9a1c', sizes: '100vw' });
// src:    /v1/img/acme/3f9a1c/960.webp
// srcSet: /v1/img/acme/3f9a1c/160.webp 160w, /v1/img/acme/3f9a1c/320.webp 320w, ... /v1/img/acme/3f9a1c/1600.webp 1600w
// sizes:  100vw

The ladder stops lower when the source is smaller:

src ends in Candidates up to
nothing (/v1/img/acme/3f9a1c) 1600
sm.webp (400 px) 480
md.webp (800 px) 960
lg.webp (1600 px) 1600
a width (640.webp) that width
orig.jpg, or a signed URL (?sig=) no srcset: the URL is used as it is

maxWidth (or the largest of <Image widths>) caps it further. A 300-pixel thumbnail slot needs nothing above 640 even on a sharp phone screen: responsiveImage({ src, sizes: '150px', maxWidth: 640 }).

Unsplash pictures get ?w= candidates from the widths list instead, capped at the w (times dpr) in their URL, with auto=format added so the browser gets WebP or AVIF.


Choosing sizes

srcset lists the files. sizes tells the browser how wide the picture will be on screen, before the CSS has loaded, so it can pick a file. The browser multiplies that width by the screen's pixel density and takes the first candidate that is wide enough.

Write sizes from your CSS:

Layout sizes
full width at every size (a hero) 100vw
2 columns on phones, 4 from 768 px (min-width: 768px) 25vw, 50vw
half the page from 1024 px, else full (min-width: 1024px) 50vw, 100vw
a container that stops at 1200 px, 3 columns (min-width: 1200px) 400px, 33vw
a fixed 80 px thumbnail 80px

Rules:

  • Conditions are read left to right; the first that matches wins. End with a size that has no condition.
  • Close is good enough. Leave out the gaps and padding: a few pixels change nothing.
  • Too large wastes bytes on every phone. Too small makes the picture blurry. When in doubt, measure the rendered width in the browser's developer tools at a phone and a desktop width.
  • Without sizes, <Image> uses (max-width: <width>px) 100vw, <width>px when you set width, else 100vw. That is right for a picture shown at its own width, and too large for a grid. Pass sizes for every picture in a grid.

Priority and LCP

The LCP (Largest Contentful Paint) is the moment the biggest thing on the first screen appears. On most storefront pages it is the hero picture. To make it early:

  1. Mark the block lcp: true (data.md). Its data comes with the first part of the page, so the block is in the first HTML instead of streaming in later.
  2. Put priority on its main <Image>. The picture loads eagerly with fetchpriority="high".
  3. Mark one picture per page. Two high-priority pictures compete for the same bandwidth.
  4. Never lazy-load the LCP picture, and never hide it behind an island or a carousel that waits for JavaScript.

The Bun storefront also does this for you: it takes the first <img> of the first content blocks (header and announcement blocks are skipped) that are in the first HTML, makes it eager and high priority, and adds a <link rel="preload"> for it, with its srcset and sizes, to the page's <head>. An image with fetchpriority="low" or "auto" opts out. Set priority yourself anyway: it is explicit, and it works on every host.

A hero block. Create blocks/hero-banner/hero-banner.tsx:

blocks/hero-banner/hero-banner.tsx
import { block, f, Image, Link } from '@bizzpocket/theme';
import './hero-banner.css';

export default block({
  name: 'Hero banner',
  category: 'hero',
  // The page's biggest element: in the first HTML, never streamed in later.
  lcp: true,
  fields: {
    image: f.image(),
    heading: f.text({ default: 'New season, new colours' }),
    link: f.link({ default: '/shop' }),
    button: f.text({ default: 'Shop now' }),
  },
  render: ({ image, heading, link, button }) => (
    <section className="hb">
      {image ? (
        // 16:9 at its full width. `priority`: loaded first, never lazily.
        <Image src={image.src} alt={image.alt ?? ''} width={1600} height={900} sizes="100vw" priority className="hb-img" />
      ) : null}
      <div className="hb-text">
        <h1>{heading}</h1>
        <Link href={link ?? '/shop'} className="hb-cta">
          {button}
        </Link>
      </div>
    </section>
  ),
});

Its CSS, blocks/hero-banner/hero-banner.css:

blocks/hero-banner/hero-banner.css
.hb { position: relative; }
.hb-img { display: block; width: 100%; height: auto; aspect-ratio: 16 / 9; object-fit: cover; }
.hb-text { padding: 1.5rem 1rem; }
.hb-cta { display: inline-block; padding: 0.75rem 1.25rem; }

CLS: keep the layout still

CLS (Cumulative Layout Shift) measures how much the page jumps while it loads. A picture without a known size takes no space until it arrives, then pushes everything below it down. The rules:

  • Always give width and height, or an aspect-ratio in CSS. They need not be the file's real pixels, only its proportions: width={4} height={5} reserves a 4:5 box.
  • In CSS, set one dimension and let the other follow: width: 100%; height: auto;. Setting both to fixed values squashes the picture, and height: auto without width/height attributes reserves nothing.
  • Use object-fit: cover with aspect-ratio when pictures of different shapes must fill the same box (a product grid).
  • Reserve space for what comes later: a review stars row, a "3 in your cart" line, a message under a form. Give it a fixed height, or put it where nothing moves below it.
  • Do not insert banners above content after the page has loaded. Render them on the server.

A product grid with fixed boxes. Create blocks/photo-grid/photo-grid.tsx:

blocks/photo-grid/photo-grid.tsx
import { block, f, Image, Link, products } from '@bizzpocket/theme';
import './photo-grid.css';

export default block({
  name: 'Photo grid',
  category: 'products',
  fields: {
    collection: f.collection(),
    count: f.number({ default: 8, min: 2, max: 24 }),
  },
  data: ({ collection, count }) => ({ items: products({ collection, first: count }) }),
  render: ({ items }) => {
    const list = items?.products ?? [];
    if (list.length === 0) return null;
    return (
      <ul className="pg">
        {list.map((p) => (
          <li key={p.id}>
            <Link href={`/products/${encodeURIComponent(p.handle)}`}>
              {/* Same 4:5 box for every product, whatever the photo's shape. */}
              {p.image ? (
                <Image src={p.image.src} alt={p.image.alt} width={400} height={500} sizes="(min-width: 768px) 25vw, 50vw" className="pg-img" />
              ) : (
                <span className="pg-img pg-empty" />
              )}
              <span>{p.title}</span>
            </Link>
          </li>
        ))}
      </ul>
    );
  },
});

Its CSS, blocks/photo-grid/photo-grid.css:

blocks/photo-grid/photo-grid.css
.pg { display: grid; gap: 1rem; grid-template-columns: repeat(2, 1fr); list-style: none; margin: 0; padding: 0; }
@media (min-width: 768px) { .pg { grid-template-columns: repeat(4, 1fr); } }
.pg-img { display: block; width: 100%; height: auto; aspect-ratio: 4 / 5; object-fit: cover; }
.pg-empty { background: #f2f2f2; }

The sizes matches the CSS: two columns (50vw) on phones, four (25vw) from 768 px.


A performance budget

The build does not stop you at a size. These are the numbers to aim for on a phone over a slow 4G connection. Check them on every release.

What Budget Why
Your islands' JavaScript on one page (client gz of the blocks it uses, added up) under 30 KB gzip every byte must download, parse and run before the island responds
One island under 10 KB gzip most islands are a few hundred bytes to 2 KB
CSS on one page (the global CSS plus the css gz of its blocks) under 14 KB gzip up to 14 KB the Bun storefront puts it inline in the page; above it the page links a separate file, one more request before the first paint
The LCP picture under 150 KB at phone width it decides when the page looks ready
Pictures on the first screen, all together under 300 KB at phone width
Server data static for every block that can be a runtime block costs one more round of fetches

How to stay inside it:

  • Prefer sir.* attributes to islands. They cost your theme nothing: the runtime is already on the page.
  • Keep heavy npm packages (date libraries, carousels, icon sets) out of islands. They are bundled into each island that imports them.
  • Give every picture a correct sizes, cap thumbnails with maxWidth or widths, and keep pictures below the first screen lazy (the default).
  • Upload pictures no larger than needed. The CDN never serves more than 1600 px wide.

React and the SIR runtime are served once per page by the storefront and shared by every block. They are not in your numbers, and you cannot make them smaller.


Reading the build size report

bunx bizzpocket build prints one row per block. For a theme with the two blocks above and the newsletter form:

block           server B  client gz  css gz  data
--------------  --------  ---------  ------  ------
hello                292          0       0  none
hero-banner          898          0     153  none
newsletter-box       553       1287       0  none
photo-grid          1038          0     206  static
total                          1287     270
Column What it is What to watch
block the block's folder name
server B bytes of the block's code in the server bundle. It never reaches the browser. nothing, unless it grows very large
client gz gzip bytes of the block's islands: the JavaScript it sends to the browser 0 for a block with no 'use client' file. Keep the rest small.
css gz gzip bytes of the block's own CSS. Only pages that use the block load it.
data none, static or runtime (data.md) a runtime block gets a line below the table saying why
total the sum of every island, and the whole stylesheet (global CSS plus every block)

The same report is in dist/size-report.json (clientGzipBytes, cssGzipBytes, serverBytes, data, and reason / detail / at for runtime blocks). bizzpocket build --json prints it instead of the table, so CI can check the budget:

bash
bizzpocket build --json | jq -e '[.blocks[].clientGzipBytes] | max < 10240'

total counts every island in the theme, but a page loads only the islands of the blocks it shows. For one page, add up the client gz of its blocks.

Next: limits.md.