Get Started with Shopify's New Headless Hydrogen Framework

Checkout examples of stores build with Hydrogen here:
hydrogentemplates.io

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.

So what is Shopify Hydrogen?

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:

1. SSR & Server Components

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.

Server Components
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.

2. Creating a Hydrogen App & Shopify Store Connection

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 shopify.config.js

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.

3. Basic Customization

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 src/components folder.

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:

Lets get started on that query by using GraphQL.
I want to quickly point out, the demo store comes with the GraphiQL Explorer.

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:

4. Product Page Edits

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 Layout.server.jsx

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.

As we can see now, there are two white borders on the top and the bottom, and it does a slight zoom in effect when hovering, but when we replace this code:

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.

Product Details

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 we're going to replace this code with this code here.

This is removing the buy now button, keeping the add to cart, button and changing the add to bag to read, add to cart:

And as we can see the buy it now button has been removed and add to bag has been changed to add to cart.

5. Color Swatches

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:

Right below this div, we can just open up JavaScript notation, and we can then check if name of our option includes the word 'color':

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.

Full Docs and Image Source

Article written by Philip Beauford for buildnextshop.com

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!

Comments

[Hidde]

Good post 👍

[Justin]

Great work👌

[Software Developer]

I want to know I can make multi store function by using Hydrogen.
I think it is possible.
Let me know your thoughts.

[Software Developer]

Hooks and components for localization: By developing shopping experiences in local languages and currencies, localization may help retailers expand their business to a global audience. The Storefront API’s localization field is automatically queried for the ISO code, country name, and available nations by the LocalizationProvider component, which saves this information in a context.