Deprecation Warning

At the beginning of 2023, the Hydrogen ecosystem changed a lot. The framework was rebuilt from scratch using Remix and Oxygen is now available for all Shopify plans. The main objective of this template was to help integrate hydrogen with Vercel, and now that Oxygen is available to everyone, there is no use for it anymore. Furthermore, after the major rewrite of hydrogen, a lot of configuration files are no longer compatible with this template.

So, this script is now deprecated. It is highly encouraged to start a new Hydrogen application following the official documentation. This README, however, still contains some useful information that might be worth reading.

Overview

This is a template for Hydrogen version 1, a React framework and SDK that you can use to build fast and dynamic Shopify custom storefronts. To be more specific, it uses the Demo Store template.

What's included in this template

• Husky git hooks (pre-commit and on the commit message)
• Vercel GitHub Actions integration (with E2E testing)
• Readme with best practices

For Klaviyo integration please visit the documentation and integration guide

Project setup

• Shopify

  • Create a shopify partner account
  • Create 2 development stores (for production and staging)
  • Connect the store to Hydrogen: Go to Settings -> Apps and sales channels -> Develop apps for your store -> create an app -> get your API keys under the API credentials tab
  • On hydrogen, save the storefront API token to your PUBLIC_STOREFRONT_API_TOKEN variable inside the .env file. And to avoid rate limiting in production I also recommend creating a delegate access token and saving it to PRIVATE_STOREFRONT_API_TOKEN (but this is optional, you can do it later if you want)

• Vercel

  • Create an account and connect it to github
  • Create a project and connect it to the repository
  • Add the environment variables by clicking on the project -> settings -> environment variables. PS: Add a different store domain and storefront API token for production and staging (vercel docs)

• GitHub

  • Create a staging branch
  • Add all the variables used inside .github/workflows/*.yaml to your GitHub repo as secrets. And use all the values for staging, not production (because these secrets will be used to run the tests inside GitHub Actions, and the tests should run on the staging environment). Without these secrets, the tests will run on the hosted demo-store from Shopify.

Architecture

This is a Frontend-only project, other tools were used to replace a custom backend. The selected e-commerce backend is Shopify. And Klaviyo was used to track events useful for marketing purposes.

The FE communicates directly to the Shopify Storefront API through hooks provided by Hydrogen (mainly the useShopQuery). If needed, the FE could call other middleware API's like Gadget, but we are avoiding that (shopify queries inside Hydrogen are more performant and easier to manage).

Environments

There are two environments: Production (the main branch) and Staging/Sandbox (the staging branch). Both have the same codebase (deeper explanation for that on Git Workflow and Hosting), the only difference between these two are which store they are connected to (we change that through environment variables on Vercel). The links for each are provided below.

• Production:
  • FE: [insert domain]
  • Shopify: [insert domain]
• Staging/Sandbox:
  • FE: [insert domain]
  • Shipify: [insert domain]

Conventions

• Git:
  • Conventional Commits (enforced pre-commit by Husky)
  • Use Rebase and Squash over Merge
• Linting: Eslint (runs pre-commit by Husky)
• Testing: E2E testing for new pages

Git Workflow

We use Trunk Based Development. So the steps for creating a new feature are:

• Create a feature branch (the branch name should be copied from the issue on Linear)
• Open PR for main
• Once approved by the devs and tested by the shareholders, merge
• GitHub Actions will automaticly merge the new code from main to staging

Hosting

The FE is hosted on Vercel. They generate an unique URL for each deploy/commit/PR (It can be shared with stakeholders/devs for testing purposes). Everything deployed from any branch other than main is connected to the Sandbox/Staging store.

A little workaround we had to make on Vercel to make Trunk Based Development work is create a separate staging branch that mirrors main. (PS: Do NOT merge any code to staging, GitHub Actions will be responsible for mirroring the branches).

CI/CD

As mentioned before, this project uses GitHub Actions as CI/CD. Currently there are 3 workflows: 2 are responsible for running E2E testing and deploying to Production and Staging and the other one is responsible for mirroring main to the staging branch.

Getting started

Requirements:

• Node.js version 16.14.0 or higher (preferably the LTS version)
• Yarn

Generating this template

Run one of the following commands:

npm init @nebulab/hydrogen

npx @nebulab/create-hydrogen

yarn create @nebulab/hydrogen

Using the latest version (recommended):

npm init @nebulab/hydrogen@latest

If for some reason the above commands don't work, you could also install the package globaly:

npm i -g @nebulab/create-hydrogen
create-hydrogen

Running the dev server

Then cd into the new directory and run:

yarn install
yarn dev

Remember to create a .env file based on .env.example.

Building for production

yarn build

Previewing a production build

To run a local preview of your Hydrogen app in an environment similar to Oxygen, build your Hydrogen app and then run yarn preview:

yarn build
yarn preview