Using Hydrogen components in Next.js

[jplhomer]

Update 10/31/2022

Good news: Hydrogen UI is now in beta. See the repo here: https://github.com/Shopify/hydrogen-ui

Moving forward, Hydrogen UI is the recommended way to use Hydrogen components in frameworks that are not Hydrogen itself.

---

Original Post (outdated)

The majority of Hydrogen components accept data from the Storefront API and render just like normal React components. This means you can use Hydrogen hooks and components in other frameworks like Next.js and Gatsby.

The Hydrogen team has not optimized for this use case for the developer preview, so you will need to follow these special instructions to make it work. While the instructions below are specific to Next.js, you can follow a similar pattern to support other frameworks.

Getting started with Next.js

In your Next.js app, you will need to install Hydrogen, react-router-dom, and next-transpile-modules:

yarn add @shopify/hydrogen react-router-dom next-transpile-modules

npm install @shopify/hydrogen react-router-dom next-transpile-modules --legacy-peer-deps --save

Next, you'll need to tell Next to compile @shopify/hydrogen from ESM to CJS by editing your next.config.js:

// next.config.js

const withTM = require("next-transpile-modules")(["@shopify/hydrogen"]);

module.exports = withTM({
  reactStrictMode: true,
});

A couple important notes about this process:

• React Router is a peer dependency of Hydrogen, and you only need to install it as a temporary workaround to prevent errors when importing Hydrogen. In a future version of a Hydrogen dev preview release, this will no longer be required.
• Hydrogen components are only exported as ESM, not CJS. We will eventually support multiple export types, so the extra transpile step will no longer be necessary.
• While React 18 Alpha is needed for Hydrogen framework applications, the stable version of React (v17 at the time of writing) can be used for Hydrogen components and hooks.

Fetching data in Next.js

We recommend calling the Storefront API on the server. Hydrogen will soon introduce a mechanism to make server-to-server calls without exhausting rate limits, so it's best to structure your apps this way from the start.

Here is an example of a product page in Next.js (pseudo-code — copy/pasting this will NOT work out of the box):

// pages/products/[handle].js
import {Product} from '@shopify/hydrogen';

export async function getStaticProps({params}) {
  const {data} = getShopifyData({query: QUERY, variables: {handle: params.handle}});
  
  return {
    props: data,
    revalidate: 5,
  };
}

export function Product({data}) {
  return (
    <Product product={data.product}>
      {/** ... */}
    </Product>
  );
}

Limitation: No useShopQuery

You cannot use useShopQuery in Next.js as it is a hook meant to be run in Hydrogen's server components. Since Next.js (stable) does does not allow you to render a component only on the server, you must fetch data in a getStaticProps or getServerSideProps function instead.

We recommend writing a utility like getShopifyData({query, variables}) which takes your storefront API credentials and makes a GraphQL query. You can then use this in the Next.js functions.

Hydrogen might introduce a utility function like this in the future.

Limitation: No server components

Hydrogen is currently using a modified version of server components which supports context and SSR. This is not yet supported in the version of server components that Next.js uses.

If you want to use the alpha version of server components in Next.js, you will need to wrap any Hydrogen component that use Context (most of them) in *.client.js components. This is the only way to currently use context Next.js server components.

Once React introduces Server Context, this limitation will no longer apply.

[mattjis]

Have you tested these methods?

While using the stable Next.js (without server components) I am unable to import anything from @shopify/hydrogen without getting the following error:

*Server Error*
SyntaxError: Unexpected token 'export'
This error happened while generating the page. Any console logs will be displayed in the terminal window.


*Call Stack*
<unknown>
/Users/mattijs/Documents/GitHub.nosync/cash-only/node_modules/ (shopify/hydrogen/dist/esnext/index.js (1)

Object.compileFunction
node://vm (352:18)

wrapSafe
node://internal/modules/cjs/loader (1031:15)

Module._compile
node://internal/modules/cjs/loader (1065:27)

Object.Module._extensions..js
node://internal/modules/cjs/loader (1153:10)

Module.load
node://internal/modules/cjs/loader (981:32)

Function.Module._load
node://internal/modules/cjs/loader (822:12)

Module.require
node://internal/modules/cjs/loader (1005:19)

require
node://internal/modules/cjs/helpers (102:18)

Object.@shopify/hydrogen
file:///Users/mattijs/Documents/GitHub.nosync/cash-only/.next/server/pages/index.js (42:18)

And when I'm using the alpha Next.js server components I am unable to use the useShopQuery hook or the provided workaround (wrapping these components in a client component) as that's not allowed either "a server component can not be imported by a client component". We also can't call the useShopQuery hook from a client component.

Not sure what to do here.

[frandiox]

@jplhomer I forgot to click Reply so my previous messages was sitting there for a while 😂 Great to have that in the OP as well!

[mattjis]

@frandiox I thought they were supported by default ever since Next.js 12?
https://nextjs.org/blog/next-12#es-modules-support-and-url-imports

[jplhomer]

@mattjis I thought so, too, but I couldn't get this to work to import Hydrogen as ESM. Super odd — perhaps we need to change our bundling strategy.

[frandiox]

I think they are supported if the exporting project has type: module in the package.json. However, we don't use that in Hydrogen because we have a mix of exports 🤔

[nandorojo]

What if you add experimental.esmExternals = true?

[mattjis]

When using getStaticProps, can we re-use the queries found in the hydrogen preview?

I have created my own getShopifyData to handle the queries:

const storeDomain = "hydrogen-preview.myshopify.com"
const storefrontToken = "3b580e70970c4528da70c98e097c2fa0"

export async function getShopifyData(query, variables) {
  return await fetch(`https://${storeDomain}/api/2021-10/graphql.json`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json",
      "X-Shopify-Storefront-Access-Token": storefrontToken
    },
    body: JSON.stringify({
      query,
      variables
    })
  }).then((response) => {
    return response.json()
  })
}

But now attempting to copy and paste the queries from the preview will result in:

{
  errors: [
  {
    message: 'Internal error. Looks like something went wrong on our end.\n' +
    'Request ID: 8cec304b-a159-4190-9a91-31960e6beb0f (include this in support requests).',
    extensions: [Object]
  }
  ]
}

Here is my full getStaticProps for clarity:

export async function getStaticProps() {
  const data = await getShopifyData(`
      query product(
        $country: CountryCode
        $handle: String!
        $numProductMetafields: Int = 20
        $numProductVariants: Int = 250
        $numProductMedia: Int = 6
        $numProductVariantMetafields: Int = 10
        $numProductVariantSellingPlanAllocations: Int = 0
        $numProductSellingPlanGroups: Int = 0
        $numProductSellingPlans: Int = 0
      ) @inContext(country: $country) {
        product: product(handle: $handle) {
          id
          vendor
          seo {
            title
            description
          }
          images(first: 1) {
            edges {
              node {
                url
              }
            }
          }
          ...ProductProviderFragment
        }
      }

      ${ProductProviderFragment}
    `,
    {
      country: "US",
      handle: "mail-it-in-freestyle-snowboard"
    }
  )

  console.log(data)

  return {
    props: {
      data: data
    },
    revalidate: 60 * 5
  }
}

[jplhomer]

Yeah I'm getting this, too.

I think it's related to their being duplicate fragments in the ProductProviderFragment we're exporting: Shopify/hydrogen#244

As a workaround, maybe install graphql-tag graphql

Wrap the query in gql as we do in our starter template.

And then:

import {print} from 'graphql';

getShopifyData({query: print(QUERY), ...});

(I have not tested this)

[mattjis]

I asked Shopify Support what the error message was and they told me: Resolution loops exceeded the number of definitions

[mattjis]

@jplhomer wrapping it in print unfortunately only partially fixes the issue.

It's now saying: Shopify: Field 'url' doesn't exist on type 'Image' x4

Could it be the /api/2021-10/graphql.json API endpoint I'm querying, that's not matching the hydrogen-preview?

[mattjis]

@jplhomer using the unstable graphQL fixes the final little issues!

[mattjis]

We recommend calling the Storefront API on the server. Hydrogen will soon introduce a mechanism to make server-to-server calls without exhausting rate limits, so it's best to structure your apps this way from the start.

Can we get any more information about this new mechanism?

When using getStaticProps we also need to provide getStaticPaths — an array of all the product handles. Which is very expensive right now.

[jplhomer]

We don't have any more information at this time about the server-to-server mechanism.

What I'd recommend is to build only a small subset of pages (maybe most popular?) during getStaticPaths and use fallback: true to generate new pages at request time for the first visit: https://nextjs.org/docs/basic-features/data-fetching#when-is-fallback-true-useful

You pay an initial fetching cost during the first render, but future renders should happen async.

[beamercola]

@jplhomer any updates on this?

[jplhomer]

@beamercola none right now. We will provide more information when we have it. For now, please take a look at my recommendation above.

[bastienrobert]

What I'd recommend is to build only a small subset of pages (maybe most popular?) during getStaticPaths and use fallback: true to generate new pages at request time for the first visit: https://nextjs.org/docs/basic-features/data-fetching#when-is-fallback-true-useful

Updated link: https://nextjs.org/docs/api-reference/data-fetching/get-static-paths#when-is-fallback-true-useful

[bastienrobert]

About server-to-server requests: https://shopify.dev/api/storefront#rate_limits

[andresespinosapc]

We recommend calling the Storefront API on the server. Hydrogen will soon introduce a mechanism to make server-to-server calls without exhausting rate limits, so it's best to structure your apps this way from the start.

I'm thinking of using Vue with Nuxt, will that mechanism be easy to implement in that or other frameworks?

[hmiller020414]

I am importing renderHydrogen into my app and calling it around my App export just like in the example here: https://stackblitz.com/edit/shopify-hydrogen-ajtgy7?file=src%2FApp.server.jsx&title=Hydrogen

When I do, I receive the attached error:

How can I use renderHydrogen and the ShopifyProvider and CartProvider in NextJS without the virtual__hydrogen.config.ts and virtual__hydrogen-routes.server.jsx files?

[juanpprieto]

This won't work. Next uses webpack and Hydrogen uses Vite. Although hydrogen has a set of UI components, at this point in time they can't be be used outisde of Hydrogen the framework.

[ryanleichty]

Are there any news or updates on using Hydrogen components in Next.js? Are the workarounds mentioned still required?

[beamercola]

@ryanleichty @suntudo I have a few projects using hydrogen - it's doable, it's not that far from this guide (the context provider is funny, happy to share my setup)

From what I understand hydrogen-ui will be our savior. Can track it here: https://github.com/Shopify/hydrogen/issues?q=label%3Ahydrogen-ui+

[ryanleichty]

@beamercola Awesome, I had no idea about hydrogen-ui! Glad it’s already in the works. I would love to see your setup if you don’t mind—I’m looking to build a new site with that combo.

[suntudo]

I'd also love to hear about any updates on this front. Also a demo repo would be 👌

[ryanleichty]

A demo would be really helpful!

[victorpmlr]

Hi,

Are we supposed to be able to use hooks? like useCart
Wrapping my cart in CartProvider & the app in ShopifyProvider raises the following error: ReferenceError: __HYDROGEN_TEST__ is not defined

The const is defined in vite-plugin-hydrogen-config.ts

Edit: seems like that's what this issue and that one are about.

[bhopalg]

Hi, did this get fixed?

[jplhomer]

👋 Hey friends! Good news: Hydrogen UI is now in beta

See the repo here: https://github.com/Shopify/hydrogen-ui

Note that the API is subject to change, so use it at your own risk. We're currently targeting Next.js and Remix as examples as we build out the package.

[jplhomer]

@suntudo it seems like it would work fine with Next 13. Components with interactivity or context need to be rendered within a client boundary with "use client". We might update hydrogen-ui exports to include those directives at the top as well.

[beamercola]

@jplhomer Any chance we'll see the Analytics component coming for Next 13?

[jplhomer]

@beamercola Analytics support is a no-brainer for headless merchants and devs, so it's definitely on our list. Whether this is a drop-in component or good documentation with which endpoints to hit and which schema, along with helper libraries—I'm not sure exactly!

[beamercola]

@jplhomer any way to get this would be a win for my clients - is it possible today through workarounds?

[jplhomer]

All the code is open sourced, so you could definitely rig up your own if you wanted! https://github.com/Shopify/hydrogen/blob/v1.x-2022-07/packages/hydrogen/src/foundation/Analytics/connectors/Shopify/ShopifyAnalytics.client.tsx