Insights

A Shopify store in 3D: what Kerf & Burl taught me

A Shopify store in 3D: what Kerf & Burl taught me

Kerf & Burl is a woodshop that does not exist. I invented it, a one-person turner in the Oregon Coast Range, so I would have a reason to write a Shopify theme from scratch and take it further than most briefs allow: 3D on the product pages, a board you configure and price yourself, and a catalogue that reads as if the maker wrote it. Nothing in it is for sale. The case study shows the finished store. This post is about what I learned on the way, nearly all of it on 15 November.

Most pieces in the shop have a 3D model, made in Blender, that you can turn with a finger or a mouse. That one decision drove almost everything below.

Shopify's own 3D viewer was the first thing I replaced

For a merchant, Shopify handles 3D well. You upload a GLB file and, in Shopify's words, "files are converted to ensure both a .USDZ and .GLB version of the model is available", which is the format an iPhone needs to place the piece on your table in AR. I kept all of that: the upload, the conversion and the hosting.

The storefront side is another matter. The two features a theme normally switches on to show those models, model-viewer-ui and shopify-xr, load model-viewer 1.12, an old release of Google's 3D viewer with flat lighting and a black ground. A theme that also wants a current copy ends up with two scripts racing to define the same element, and whichever arrives first decides how the page looks. So the theme carries model-viewer 4.4.0 as one of its own files, uses neither feature, and opens AR itself. Two smaller leftovers needed the same treatment: Shopify's model tag writes a black background straight onto the element and fixes the lens at 45 degrees, so the stylesheet overrides one and the theme passes auto for the other.

The lesson I would hand to anyone doing this: keep Shopify for the media pipeline, and own the viewer. The viewer is where the store's look lives.

Owning it also meant framing. A turned vase is tall and narrow, a platter long and flat, and a fixed camera distance suits neither. The Browse in 3D page measures each model's bounding box and sets the camera so the whole piece fits both the height and the width of the stage, never closer than 1.1 times its farthest corner. No product carries a hand-tuned number.

A board builder where Shopify still holds every price

The builder lets you choose a cutting board's wood, size and edge, and watch it change in 3D. The tempting way to build that is an app with its own pricing table. I kept it inside Shopify instead: five woods, three sizes and three edges make 45 real variants of one product, so the price a visitor sees is the price Shopify charges, and checkout, discounts and reports need no special handling.

Diagram of the board builder: wood is a material variant inside one GLB file, so nothing downloads; size, edge and juice groove swap between 18 GLB files, loaded when a choice is pointed at; every combination is one of 45 priced Shopify variants; paid extras join the cart as lines of a hidden add-on product tied to the board by a shared build id.
Wood changes the material in place. Size, edge and groove change the file.

What the 3D does depends on which choice changed. Wood is the cheap one: all five woods live inside the same model file as material variants, a glTF extension called KHR_materials_variants, so switching from walnut to cherry swaps the surface without downloading anything. Size, edge and juice groove change the board's shape, which means a different file, eighteen in all. The builder starts fetching a file as soon as the pointer rests on, or the keyboard focuses, the choice that would need it, and once the page is idle it quietly fetches the other edges for the current size. By the time most people click, the file is already there.

Paid extras posed a different problem. An oil and hardwax finish adds $20, a juice groove $25, and engraving of up to 24 characters $30. Those go into the cart as variants of a hidden add-on product, in the same request as the board, and every line carries the same hidden build id. The cart reads that id, so changing the board's quantity or removing it takes its extras along.

The Build your board page on the Kerf and Burl dev store: an end-grain cherry board in 3D beside the wood swatches, size and edge choices, with Large and Round-over selected and a price of $360.
Cherry, large, round-over: $325 for the size, $20 for the wood, $15 for the edge. Illustrative prices; nothing is for sale.

One finding from the builder surprised me. The oiled boards looked wrong: at low angles the top face washed out to a white sheen, more like a varnished table than an oiled board. In glTF, a material's roughness setting is multiplied by its roughness map. The high-resolution maps averaged about 0.4, so an oil finish set at 0.62 actually rendered at about 0.25, far shinier than intended. The theme now drops the map before it applies the finish's roughness, and the boards look like oiled wood again.

Loading, zoom and the scroll wheel

A 3D model takes a few seconds on a slow connection, and a grey box with a spinner tells a visitor nothing. Each stage instead shows the piece's own photograph run through an SVG filter that turns it into an ink outline. The outline draws itself in as the file downloads, then cross-fades to the live model. If anything goes wrong, whether scripts are off, the model fails or twelve seconds pass, the stage falls back to the plain photograph.

Two phone screenshots of the Browse in 3D page side by side: on the left a standing sculpture drawn as a partly traced ink outline on its plinth while the model downloads; on the right the finished 3D model in madrone.
The Browse in 3D page on a throttled connection: the outline mid-draw, then the model.

Zoom took more thought than I expected. model-viewer zooms on every turn of a mouse wheel and never hands the wheel back, so a visitor scrolling down a product page with the pointer over a piece found the page stuck while the piece shrank. Turning zoom off fixes that and throws away the reason for having 3D at all.

Diagram of the wheel rule in four steps: a gesture starts after a 400 millisecond pause; if it began on the page or over a piece still loading, it belongs to the page; a trackpad pinch always zooms, and a plain wheel zooms while the piece has room to zoom that way; otherwise the page scrolls.
One listener decides who owns each wheel gesture, once, at its start.

The answer is a single listener that decides who owns each wheel gesture, once, when it starts. A trackpad pinch always zooms the piece. A plain wheel zooms only while the piece has room to zoom in that direction, and since every piece rests fully zoomed out, scrolling down past one simply scrolls the page. A scroll that began on the page stays a scroll when the pointer crosses a piece. The listener never blocks the page's own scrolling; it only keeps the wheel away from the viewer. Product pieces zoom to about 2.3 times, where their textures still hold up; the builder's boards, with sharper textures, go to about 3.2. On a phone none of this arises: one finger scrolls the page and two pinch the piece. Phones raise other questions, which I covered in keeping three.js smooth on an iPhone.

The afternoon the 3D went quiet

At 2:39 that afternoon I committed the change that moved every 3D stage onto the theme's own viewer. It touched nine theme files. Shopify themes reach a store through shopify theme push, whose --only flag uploads just the files you name, which is handy for small changes. The push that followed named only the gallery's files.

Diagram of the partial push: of nine changed theme files, only the gallery section reached the store; eight never arrived, including the viewer script itself; nothing defined the model-viewer element, so every stage showed its still photograph; the fix was pushing the full set and checking the live page.
The gallery switched Shopify's viewer off. The theme's viewer was not there to take over.

The gallery section on the store now told Shopify not to load its old viewer, but the file that replaced it had never been uploaded. Nothing on the page defined the 3D element, so every stage showed its fallback photograph. Because those photographs are good, the pages looked finished. A check of the live store caught it the same afternoon, and the fix needed no code at all: push the eight missing files, then confirm on the live store that the element was defined, a model loaded, a drag turned it, and no request failed.

I took two habits from it. After a commit that touches several theme files, push the commit's whole set, not the file I happen to be thinking about. And verify a 3D page by asking the page whether the viewer exists, rather than by looking at it. A fallback designed to look fine will hide a failure from anyone who only looks.

Housekeeping a shopper never sees

Some of the most useful work was invisible. The add-on product behind the builder's extras has to stay published, or the cart cannot hold its variants, but a shopper should never meet a product called "Board add-ons". Its product type keeps it out of every collection grid, the piece count, the type filter, the featured rows, search, the search suggestions, the recommendations and the recently viewed row, while the builder carries on using it.

Filtering changes how many pieces a grid shows, and a lone piece on the last row of a grid looks like a mistake. Rather than stretch it into a thin strip, the theme turns that last piece into a feature card: the photograph whole, the wood, the name, a line of description, the price, and a button that swaps the photograph for the live model.

A feature card at the end of the shop grid filtered to cherry: a live-edge cheese board turned to 3D on the left, and on the right its woods, name, one-line description, the price of $95, a Show the photo button and a See this piece button.
The grid's last piece, filtered to cherry, with its 3D model switched on.

When the final high-resolution media arrived, it went in through Shopify's Admin API rather than the admin screens. The 71 replaced photographs used fileUpdate, which replaces a file's content and keeps its URL, so each kept its place, its alt text and its id. Nine new photographs were added and put in order. The 39 models took a longer route, because that direct replacement covers images and other files but not models: upload the new one, attach it, wait until Shopify reports it ready, move it into the old one's slot, then delete the old one. Shopify makes the iPhone version of each new model itself, as it does for any model uploaded through the admin.

One last snag came from the public preview of the theme, which runs on this site behind Cloudflare. After the swap, Cloudflare went on serving the old photographs, because the new files had the same names. Every image address in the preview now ends in a short fingerprint of the file's contents, so a changed photograph gets a new address and no cache can hold on to the old one.

What is next

There is one loose end. The roughness fix lives in the theme's code, and AR on an iPhone never runs that code: it reads the model file Shopify converted, roughness maps and all. So a cherry board placed on a real kitchen counter is still shinier than the same board in the browser. The fix belongs in the model files, with roughness maps that average about 0.75 instead of 0.4, and that is the next thing I open in Blender.

You can walk around the store yourself. The public preview needs no password; the store on Shopify is at kerf-and-burl.myshopify.com, password ulric_shopify. If you would like a theme like it for a shop that does exist, my build service covers Shopify stores.

Common questions

Is Kerf & Burl a real shop?

No. It is a concept store I built to show a custom Shopify theme. The woodshop, its products and its prices are invented, and nothing is for sale.

How can I see it?

The public preview at ulric.studio/demos/shopify/kerf-and-burl/ needs no password. The store on Shopify is at kerf-and-burl.myshopify.com, with the password ulric_shopify.

Is it built on a premade theme?

No. The theme was written from scratch as a Shopify Online Store 2.0 theme, following the conventions of Shopify's Horizon theme, with its own copy of model-viewer for the 3D.

Can you build a store like this for my business?

Yes. I build custom Shopify themes, with or without 3D, and quote each one per project.

Related

← All insights