GraphQL Queries for Implementing a Custom Shopify Storefront

Steps to create a Shopify online shop with Next.js and the Storefront API.

When you decide to create a custom online shop with Shopify, you can program a standard Liquid-based theme or use the Shopify storefront API. Using Shopify as a headless backend and developing the frontend in Next.js or the future, Hydrogen is a good option when performance and custom control are your primary goals. Here I list some useful GraphQL queries to quickly get you up and running.

This article assumes you have some basic knowledge of Next.js, React, and GraphQL. It shows you the required GraphQL queries for creating a Shopify online shop using Shopify’s headless storefront API.

For simplicity, all queries are called from the client. Choosing the correct data fetching strategy for your use case is essential for the best results.

Project setup

I created a standard Next.js project and installed the following additional dependencies:

• prisma-labs/graphql-request: https://github.com/prisma-labs/graphql-request
• garmeeh/next-seo: https://github.com/garmeeh/next-seo (optional)
• Tailwind CSS: https://tailwindcss.com/ (optional)

I structure my directories to reflect the directory structure of Liquid-based themes:

./pages
    cart
      [[...id]].js
    pages
      handle1.js
      handle2.js
      ...
    policies
      legal-notice.js
      privacy-policy.js
      refund-policy.js
      shipping-policy.js
      terms-of-service.js
    products
      [id].js
    _app.js
    collections.js
    index.js

This tutorial shows you the required GraphQL queries for products and cart. I use Server-Side Rendering (SSR — getServerSideProps) to load the initial products and cart data. SSR is also needed if you’d like to optimize your pages with SEO information from the Shopify backend.

Calling the Shopify GraphQL APIs

graphql-request is a minimal GraphQL client library perfect for accessing the Shopify GraphQL API. Therefore I create a small utility class to simplify my calls.

./utils/shopify.js
import { GraphQLClient } from 'graphql-request'
const shopify = async (query, variables) => {
  const endpoint = process.env.NEXT_PUBLIC_STOREFRONT_ENDPOINT
  const token = process.env.NEXT_PUBLIC_STOREFRONT_API_TOKEN
  const graphQLClient = new GraphQLClient(endpoint, {
    headers: {
      'X-Shopify-Storefront-Access-Token': token,
    },
  })
  return await graphQLClient.request(query, variables)
}
export default shopify

See: Get the API credentials for a custom app and Endpoints and queries.

I can then make the GraphQL calls (e.g., get the product based on the product handle).

import shopify from '../../utils/shopify'
...
const getProduct = async (id) => {
  const query = gql`
    query getProduct($handle: String!) {
      product(handle: $handle) {
        id
        title
      }
    }
 `
  const variables = { handle: id }
  const data = await shopify(query, variables)
}

See: https://shopify.dev/api/storefront/latest/queries/product

Product page

For the product page, I need at least these 2 GraphQL queries:

• get the product
• add the product to the shopping cart

I need the cart ID on multiple pages. Therefore I store it in the Window.sessionStorage.

Here is my simplified product page:

./pages/products/[id].js
import Image from 'next/image'
import { useState } from 'react'
import { gql } from 'graphql-request'
import Layout from '../../components/Layout'
import shopify from '../../utils/shopify'
const getProductQuery = gql`
  query getProduct($handle: String!) {
    product(handle: $handle) {
      id
      handle
      seo {
        title
        description
      }
      title
      descriptionHtml
      priceRange {
        minVariantPrice {
          amount
          currencyCode
        }
      }
      featuredImage {
        url
        altText
        width
        height
      }
      variants(first: 10) {
        edges {
          node {
            id
          }
        }
      }
    }
  }
`
const createCartMutation = gql`
  mutation cartCreate($input: CartInput) {
    cartCreate(input: $input) {
      cart {
        id
      }
    }
  }
`
const updateCartMutation = gql`
  mutation cartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
    cartLinesAdd(cartId: $cartId, lines: $lines) {
      cart {
        id
      }
    }
  }
`
const Product = ({ product }) => {
  const [quantity, setQuantity] = useState(1)
  const getLines = () => [
    {
      quantity: parseInt(quantity),
      merchandiseId: product.variants.edges[0].node.id,
    },
  ]
  const handleAddToCart = async () => {
    let cartId = sessionStorage.getItem('cartId')
    if (cartId) {
      const variables = {
        cartId,
        lines: getLines(),
      }
      const data = await shopify(updateCartMutation, variables)
    } else {
      const variables = {
        input: {
          lines: getLines(),
        },
      }
      const data = await shopify(createCartMutation, variables)
      cartId = data.cartCreate.cart.id
      sessionStorage.setItem('cartId', cartId)
    }
  }
  return (
    <Layout>
      <h1 className="text-xl">{product.title}</h1>
      <div>
        <Image
          src={product.featuredImage.url}
          alt={product.featuredImage.altText}
          width={product.featuredImage.width}
          height={product.featuredImage.height}
        />
      </div>
      <div 
        className="prose"
        dangerouslySetInnerHTML={{
          __html: product.descriptionHtml,
        }}
      />
      <div>{product.priceRange.minVariantPrice.amount}</div>
      <input
        type="number"
        name="quantity"
        value={quantity}
        onChange={(e) => setQuantity(e.target.value)}
      />
      <button onClick={handleAddToCart}>
        Add to basket
      </button>
    </Layout>
  )
}
export const getServerSideProps = async (context) => {
  const { id } = context.query
  if (!id) {
    return { notFound: true }
  }
  const variables = { handle: id }
  const data = await shopify(getProductQuery, variables)
  return {
    props: {
      product: data.product,
    },
  }
}
export default Product

Cart page

On the cart page, I have to use at least these 2 GraphQL calls:

• load all cart lines
• remove an item from the cart

In this case, I decided to load the cart items on the server using SSR. Therefore the cart link may contain the cart ID in the path. You can achieve this by using Next.js dynamic routes.

./pages/cart/[[…id]].js
import Link from 'next/link'
import Image from 'next/image'
import { gql } from 'graphql-request'
import shopify from '../../utils/shopify'
import Layout from '../../components/Layout'
const getCartQuery = gql`
  query getCart($id: ID!) {
    cart(id: $id) {
      id
      lines(first: 50) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
                priceV2 {
                  amount
                  currencyCode
                }
                image {
                  url
                  altText
                  width
                  height
                }
                product {
                  id
                  title
                  handle
                }
              }
            }
          }
        }
      }
      estimatedCost {
        totalAmount {
          amount
          currencyCode
        }
      }
      checkoutUrl
    }
  }
`
const removeItemMutation = gql`
  mutation cartLinesRemove($cartId: ID!, $lineIds: [ID!]!) {
    cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
      cart {
        id
      }
    }
  }
`
const Cart = ({ cart }) => {
  const handleRemoveItem = async (cartId, lineId) => {
    const variables = {
      cartId,
      lineIds: [lineId],
    }
    await shopify(removeItemMutation, variables)
  }
  return (
    <Layout>
      <h1 className="text-xl">Cart</h1>
      <form action={cart.checkoutUrl} method="GET">
        <ul>
          {cart.lines.edges.map((item) => {
            const variant = item.node.merchandise
            return (
              <li key={item.node.id}>
                <div>
                  <Image
                    src={variant.image.url}
                    alt={variant.image.altText}
                    width={variant.image.width}
                    height={variant.image.height}
                  />
                </div>
                <Link href={'/products/' + variant.product.handle}>
                  <a>{variant.product.title}</a>
                </Link>
                <div>{variant.priceV2.amount}</div>
                <div>Quantity: {item.node.quantity}</div>
                <button
                  onClick={() => {
                    handleRemoveItem(cart.id, item.node.id)
                  }}
                >
                  Remove
                </button>
              </li>
            )
          })}
        </ul>
        <h2>Total</h2>
        <div>{cart.estimatedCost.totalAmount.amount}</div>
        <button type="submit">Checkout</button>
      </form>
    </Layout>
  )
}
export const getServerSideProps = async (context) => {
  const { id } = context.query
  if (!id) return { props: {} }
const variables = { id: id[0] }
  const data = await shopify(getCartQuery, variables)
return {
    props: {
      cart: data.cart,
    },
  }
}
export default Cart

Tip: Use pagination to retrieve all cart lines! https://shopify.dev/api/usage/pagination-graphql

For a live example, see my latest project (in German).

Hexa 3D

Conclusion

The future of Shopify is Hydrogen. Hydrogen offers a set of React components to develop custom storefronts. It hides a lot of complexity (e.g., GraphQL queries) from the developer and brings tremendous benefits (e.g., performance improvements). But it’s not available yet.

This tutorial showed you how to use Shopify as a headless e-commerce platform using Next.js/React and native GraphQL queries. It can be seen as a lower level or predecessor of Hydrogen. As soon as Hydrogen is ready, I will most likely migrate my Next.js based Shopify projects.