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:
<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:
<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.webpanswers308to/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,jpegandpng. The helpers keep the format thesrchad, and usewebpwhen it had none.
So for a CDN picture, responsiveImage() writes one candidate per rung:
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: 100vwThe 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>pxwhen you setwidth, else100vw. That is right for a picture shown at its own width, and too large for a grid. Passsizesfor 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:
- 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. - Put
priorityon its main<Image>. The picture loads eagerly withfetchpriority="high". - Mark one picture per page. Two high-priority pictures compete for the same bandwidth.
- 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:
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:
.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
widthandheight, or anaspect-ratioin 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, andheight: autowithoutwidth/heightattributes reserves nothing. - Use
object-fit: coverwithaspect-ratiowhen 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:
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:
.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 withmaxWidthorwidths, 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:
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.