Create a Hydrogen app

You're ready to create a Hydrogen app. You want to set up your development environment so that you can begin coding.

In this tutorial, you'll create a Hydrogen app locally to begin developing a simple Shopify custom storefront. Hydrogen is a front-end web development framework that's optimized for commerce by Shopify.

What you'll learn

After you've finished this tutorial, you'll be able to do the following:

  • Create a new Hydrogen app
  • Customize text and component styles
  • Fetch data from server components and make changes to GraphQL queries
A GIF showing the Hydrogen starter template
Hydrogen starter template


Before you start, consider familiarizing yourself with React, Vite, and Tailwind CSS. Hydrogen is a front-end React framework. It uses Vite for server-side rendering and hydration middleware. Basic styles are provided by Tailwind CSS.

Install dependencies

If you want to test a Hydrogen app using a pre-configured demo store, then you need to only install the dependencies. This is the quickest approach.

Develop using a Shopify store

If you want to develop a Hydrogen app that uses data in your Shopify store, then you need to install the dependencies and meet the requirements to develop using a Shopify store:

  • You have an existing Shopify store that you can use for Hydrogen development.

  • You've created a private app and allowed the app to access storefront data using the Storefront API.

  • You've published products to the Online Store sales channel.

    When you create a private app, all existing products on your Shopify store are published to the Online Store sales channel, which makes them available to your Shopify storefront.

    If you add products after you create a private app, then you need to publish the products to make them available.

Step 1: Create a new Hydrogen app

You can create a Hydrogen app locally using either yarn or npm.

If you want to integrate with an existing React framework, like Next.js or Gatsby, then you can add the @shopify/hydrogen npm package to your project.

  1. Navigate to the directory where you want to create your project:

  2. Run the following command:

Update information about your Shopify storefront

To connect your Hydrogen app to your Shopify storefront, you need to update properties in shopify.config.js. The shopify.config.js file contains useful information about your storefront.

You'll need your generated Storefront API access token to access your Shopify storefront:

A screenshot of the Storefront API access token section in the Shopify admin.
The Storefront API access token section in the Shopify admin
  1. Switch to your new app's directory:

  2. Open shopify.config.js. The supported properties in the file include the following:

    Name Type Required? Default value
    locale String Yes en-us
    storeDomain String Yes
    storefrontToken String Yes The Storefront API access token for hydrogen-preview
    graphqlApiVersion String Yes unstable
  3. In shopify.config.js, make the following changes and save the file:

  • Update storeDomain with your store's domain name.
  • Update storefrontToken with your Storefront API access token.

Start a development server

Start a development server in your new app's directory:

Visit the development environment

Visit the development environment running at http://localhost:3000.

Step 2: Make customizations

Hydrogen provides a structure for building your app along with basic styles provided by Tailwind. You can customize any part of Hydrogen as long as you keep the following required files:

  • index.html
  • src/entry-server.jsx
  • src/entry-client.jsx

Change text

  1. In src/components/Welcome.server.jsx, change the Hello, Hydrogen text to Hello, Snowboards.

  2. Save the file to see your changes updated in real-time:

A GIF showing how to change text in your Hydrogen app
Changing text in your Hydrogen app

Change a component's style

  1. In src/components/Welcome.server.jsx, find the following code:

  2. Make the background color red for the Hello, Snowboards text:

  3. Save the file to see your changes updated in real-time:

A GIF showing how to change a component's style in your Hydrogen app
Changing a component's style in your Hydrogen app

Step 3: Fetch data from server components

Hydrogen offers the useShopQuery and useQuery hooks to fetch data from server components. Most src/pages/*.server.jsx components have queries in them that you can modify.


To fetch data from your Shopify storefront, you can use the useShopQuery hook. Your shop domain and token is automatically configured, so you only need to pass a GraphQL query.

The useShopQuery hook is designed to be used only in server components. This is because only server components can make calls to the Storefront API.


The useQuery hook allows you to execute an asynchronous operation like fetch in a way that supports Suspense. It's based on react-query. You can use this hook to call any third-party APIs.

Step 4: Make GraphQL changes

You might want to make changes to a GraphQL query to fetch data for a specific need. For example, if you want to display a certain product attribute or shop attribute, then you can update a query.

In src/pages/index.server.jsx, make a change to QUERY at the bottom of the file. For example, fetch information about your shop:

You can then use the new data you've requested in your server component, which is available on the page where you updated the query:

Interactive GraphiQL interface

You can explore the Storefront API and run test queries in your Hydrogen app. When you're running the Hydrogen local development server, you can visit the following URLs to load an interactive GraphiQL interface connected to your shop:

Next steps