Checkout examples of stores build with Hydrogen here:
Headless Ecommerce is carried out in multiple ways by many types of developers. Shopify has recently launched its own opinionated framework, specifically made for headless custom Shopify storefronts, so let's take a closer look.
According to Shopify, Hydrogen is a React based framework from Shopify that allows us to build custom headless Shopify storefronts, giving developers everything needed to build fast, personalized and dynamic E-commerce Shopify experiences.
If you want to take a deeper dive, here is a great article by Ilya Grigorik, who is a principal engineer at Shopify and an author of a book on high-performance browser networking.
First thing you will notice is that Hydrogen is an opinionated frameworks and is shipped with Tailwind CSS, which I personally think is great.
So why should we care about using hydrogen and how is this going to work? Let's take a deeper look, then walk through the getting started portion of the Hydrogen documentation:
When we look at the architecture, hydrogen is built on top of react 18, so it comes with all the cool react 18 features like streaming SSR (server-side rendering), progressive hydration, server components, data-fetching on servers and the suspense component.
Before making any customizations, I wanted to briefly look at Streaming server-side rendering (SSR), Server components (link) and the hydrogen file naming convention.
Let's talk about Streaming SSR.
When the client loads a page, you have time to first byte (TTFB), and the first and largest contentful paints (FCP, LCP).
With client side rendering:
As you can see here, the time to first byte is fast, but the largest paint is a little delayed and in server side rendering the time to first byte lands somewhere in the middle, but the largest paint is faster.
However, when you compare Streaming server side rendering, SSR unlocks fast non-blocking first render. So all that means is it will squish the two processes together and run them side by side, which results in a faster TTFB and FCP and LCP, which is obviously better.
And this is all powered by the suspense component.
There is an SSR Demo here that has been artificially slowed down so you can adjust the delays and see how it all works.
Now let's look at Server/ Client components and the Hydrogen rules and naming conventions related to them.
As you can see, there's a new naming convention in hydrogen with dot .server and the dot .client. That matters because in 'normal' react (.JS .JSX) files behave like we expect. In Hydrogen the .JS .JSX component behavior we expect are actually .client.JSX components, which can be confusing at first.
Shopify Partners Account
Now that we've covered some basics, we're ready to dive in.
If you already have a Shopify Partners account and development store, you can just skip to the next step.
If you don't have a Shopify partner account, you can join for free here. Proceed to log in, click on Stores in the top left, then Add store in the top right.
Then choose Development store as the store type and fill out the required information and click Save.
Shopify Storefront Access Token
So now the only thing we need to get started with the hydrogen framework is to log into our Shopify partner store and grab a storefront access token.
Once were in the store admin area we go to the Apps tab and click Develop apps and follow the accept screens:
Select all of the scopes for the Storefront API, hit Save and then Install App.
Finally, just copy the Storefront API access token to your clipboard.
Creating a Hydrogen App
All we need to create a hydrogen app is to head over to the hydrogen installation page and install Hydrogen based on your preferred platform/method.
Since I'm on Windows with Node, I'll just use NPX:
npx create-hydrogen-app (name your app) Then run: cd your-app npm install --legacy-peer-deps npm run dev
And here it's asking us to name the app. I'm just going to name it philips_hydrogen
We can then CD into philips_hydrogen and run these commands.
This will install the peer dependencies and then run our app using NPM run dev.
After running our app, we end up on the Hydrogen demo store home page at localhost:3000
What we want to do first is change the storefront access token and connect our storefront.
Open up the folder structure, and go in to
Paste in the access code in the 'storefrontToken' field, and then you're going to need to paste in your domain name as shown above.
Save this and you should see your connected store information on the home index page of the Hydrogen demo store.
Now that we have our storefront access token connected, we can jump over to VS code to make our first basic edits. The first change will be to update the existing h2 title from hello, snowboards to hello, Hydrogen. We just need to go to the
welcome.server.jsx file, which is located in the
As we can see, the h2 title has been updated.
Next, in the same file we will use Tailwind CSS to change the background to red-500:
And we see the background has updated color.
Now we're going to do a bit of data fetching from the server component. There are two custom hooks that Shopify adds to hydrogen, useShopQuery & useQuery. useQuery is for all 3rd party APIs, similar to fetch and Axios, except done in a way that supports the suspense component.
useShopQuery is used to fetch data from your Shopify store front, using the storefront access token.
All we need to do is pass a query like this:
We will have it here as an extension off of our localhost:3000/graphql
If you look at the query:
We're going to add the shop name here:
Because we're in a server component, we can console log the data, (shop name)
and this will display inside of our VSCode terminal.
As we see, the shop name is showing:
So now we're going to go do a few customizations of the product page. We're going to start by editing the layout in
And we will replace it with this code.
As we see right here, we have some localization information. We have the shop name, a homepage link and the cart, which has functionality. We also have the footer below.
And so when we replace this code with the more basic code above, that is just querying the shop name and returning no components:
We can see that we lose the header, there's no localization, the shop name has changed font size and there is no cart.
We've also lost the gradient background and the footer below.
Moving on, we're going to create a product list using our product cards.
The product list is a list of product cards that are usually mapped in from the connected store.
The product card also comes included with hydrogen as a shared component by default, which is able to be used on both client and server components.
The only visual change that we see here is the white borders are gone and there's no more zoom in effect.
Now we're going to add our product card to the product list.
We will create a new file in src/components, call it productList.jsx .
And we'll be adding this product list to the index page.
So what we're going to do is replace the current index code with this:
As we can see, we now have our product list.
Now we can create then add a load more button component, enabling us to show the rest of our product cards.
This will be a client component, so we can create that in the same src/components folder using this code:
And then what we're going to then do is import the loadMore Component to our index page
And when we save this time, we can see the load more button.
So now we're going to do our last edit, which will be in
ProductDetails.client.jsx So the first thing we'll change is the header style. We're going to look for the H1 in the file, and we're going to change the text color to purple 500.
Moving on, next we're going to update and remove components.
It's basically saying you might want to update, add to bag, to read, add to cart, which is very simple and remove the, buy it now button.
So we are going to find the following code:
And as we can see the buy it now button has been removed and add to bag has been changed to add to cart.
Okay so we're going to continue editing our product options. We will add some color swatches and this is not in the documentation, but it's a fairly quick and easy, edit for us to do, to make this look better.
First we need to open the
productOptions.jsx file. We can see the ternary conditional line here, and we're going to add in a few lines of code:
So if the name includes color, then we will put in the extra div and span you see above.
The values are mapped and each individual color would be one of the values and that will set the background color of each color swatch.
Okay awesome, we now have our color swatches showing. And these colors are actually coming from the back end in the Shopify store and the store admin back-end product page.
So that's it! I hope you enjoyed our dip into the Shopify Hydrogen framework.
Checkout the full tutorial at BuildNextShop.com where we create a fully production ready Shopify Headless store using Next.js and later adapt it to Hydrogen!