INCOMPLETE: Waterworld: Building best practice Ecommerce with Shopify

A chronology of our journey with Shopify's React-based beta on the road to a new boilerplate.

Glossary

CMS — Content Management System

CSS — Cascading Style Sheets

CSS-in-JS — A framework for writing Cascading Style Sheets within Javascript files

JS — Javascript

HMR — Hot Module Replacement

L+M — Love + Money (us)

OOTB — Out of the Box

Prologue: I can’t believe you’ve done this

wat?

This is the first in a series of articles describing our experience with Shopify Hydrogen, where we:

• Improved environment configuration and import management
• Integrated Emotion CSS-in-JS in place of Tailwind
• Integrated Sanity Connect and Sanity-driven page creation
• Added our own ‘bolt-on’ custom component structure
• Did lots of other secret, extraordinary things
• Had a great time, in the end

who?

This series will act as a snapshot of our working process, a guide to producing the same thing we did, and ultimately a view of the potential for code we see in Hydrogen. It will read as a technical guide, but we’ll be trying to make this readable for anyone who’s interested in adapting this framework for their own use.

y tho

We like React. We've settled into a comfortable groove deferring to the React-based static site generator Gatsby whenever a new project comes in. We have full control over styles, libraries, plugins, integrations, and Content Management Systems (CMS). This works wonderfully for what we call ‘brochure’ sites: websites that exist primarily to display information.

We like Sanity. With this and Gatsby together we can give clients site-wide page-builder support and globally editable content. Critically, Gatsby gives us freedom to plug in any other CMS, and we like that the most.

We like Shopify. We've built myriad brands on this platform both for ourselves and others, and experience tells us it is secure, manageable, and ubiquitous. Having been our own customers and having tried the competitors, our position is that for administration, payments and logistics in particular, it is the gold standard. For some other things, like content management and building templates, it remains wanting.

We do not like Shopify’s templating language, Liquid. It feels as old as PHP, has too many illogical quirks, and requires functional logic and product data be tangled up in templates. There are ways to ease the pain — including TailwindCSS, and the recent release of Shopify Online Store 2.0 — but we’ll cover these in another, less exciting series.

ok so

We like React & Gatsby. We like Sanity. We like Shopify. We don't like Liquid. In 2020 our solution was to go Headless, which we’ve covered elsewhere: Gatsby+CMS in the front, Shopify+Ecommerce in the back. In 2021, Shopify released a beta React-driven framework called Hydrogen. Having tried it at the end of 2021, we’re here in 2022 to tell you how it went.

You can read Shopify’s Developer Preview Documentation to get a feel for why Shopify produced this framework and what it is more generally. For the technical juice, read on.

Episode 1: Walk Toward the Vite

Hydrogen is an opinionated React framework for creating custom storefronts that work with Shopify stores. You can clone their demo, connect it to a store via their config file and start developing locally insanely fast; no more themekit deployments, no CSS/SCSS/JS precompiling, no need to even open the store in the Shopify dashboard if you have the credentials to hand. However, like all opinionated frameworks, using it OOTB like this comes with certain pros and cons. For example, keeping to Shopify’s opinion on something like folder structure makes the repository easy to share, because you can point new developers to Shopify documentation (a pro, provided it’s well written). However, you may know in your heart of hearts that every bone you command disagrees with that structure and you will never again hit proper flow until you FIX IT (uh… a con).

In working with Hydrogen we’ve attempted to apply more common sense — i.e. to make it less opinionated — while preserving everything that makes it better than the alternatives.

The result is our newly minted internal Hydrogen-based template that:

• Can make use of environment configuration and root resolver aliases
• Uses Emotion CSS-in-JS
• Uses components that are shareable with our Gatsby template
• Has CMS support (e.g. Sanity Connect)
• Retains use of Shopify’s opinionated hooks and data-tier helpers
• Can be synced to retain our work while absorbing Shopify’s updates

In this episode, we'll be focusing on the cloning process, Vite, and applying better environment configuration than their demo provides.

1.1 The 6th Day

Clone the latest version of the Hydrogen baseline on your machine by running the npx command. Give it any name — we’re calling ours “lam-hydrogen”:

npx create-hydrogen-app

npx: installed 5 in 3.155s
? Project name: › lam-hydrogen

This should initialize a new repository reminiscent of “create-react-app”: