@shopify/storefront-kit-react NPM

IMPORTANT This package is being renamed to @shopify/storefront-kit-react. All future updates will be published to that package.

React Storefront Kit

IMPORTANT: Refer to how this package is versioned.

This document contains the following topics:

Getting started

Run one of the following commands:

npm:

npm i --save @shopify/storefront-kit-react

Yarn:

yarn add @shopify/storefront-kit-react

Authenticating the Storefront client

To make it easier to query the Storefront API, React Storefront Kit exposes a helper function called createStorefrontClient().

The client can take in the following tokens:

Delegate access: Used for requests from a server or other private context. Set as privateStorefrontToken.
Public: Used for requests from a browser or other public context. Set as publicAccessToken.

The following is an example:

// Filename: '/shopify-client.js'

import {createStorefrontClient} from '@shopify/storefront-kit-react';

const client = createStorefrontClient({
  privateStorefrontToken: '...',
  storeDomain: 'myshop',
  storefrontApiVersion: '2023-01',
});

export const getStorefrontApiUrl = client.getStorefrontApiUrl;
export const getPrivateTokenHeaders = client.getPrivateTokenHeaders;
export const getShopifyDomain = client.getShopifyDomain;

You can then use this in your server-side queries. Here's an example of using it for NextJS's getServerSideProps:

// Filename: '/pages/index.js'

import {
  getStorefrontApiUrl,
  getPrivateTokenHeaders,
} from '../shopify-client.js';

export async function getServerSideProps() {
  const response = await fetch(getStorefrontApiUrl(), {
    body: GRAPHQL_QUERY,
    headers: getPrivateTokenHeaders({buyerIp: '...'}),
    method: 'POST',
  });

  const json = await response.json();

  return {props: json};
}

You can also use this to proxy the liquid online store:

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import {getShopifyDomain} from '../shopify-client.js';

export default function handler(req, res) {
  fetch(getShopifyDomain() + '/products', {
    headers: {
      /** forward some of the headers from the original request **/
    },
  })
    .then((resp) => resp.text())
    .then((text) => res.status(200).send(text))
    .catch((error) => {
      console.error(
        `Error proxying the online store: ${
          error instanceof Error ? error.stack : error
        }`
      );
      res.status(500).send('Server error occurred');
    });
}

(Optional) Set the content type for the Storefront client

By default, the Storefront client sends the "content-type": "application/json" header. Use the json content type when you have GraphQL variables and when the body is an object with the following shape:

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

However, when the body is only a query string, such as {"..."}, you can optionally change the default header to application/graphql:

createStorefrontClient({contentType: 'graphql', ...})

Alternatively, each time you get the headers you can customize which "content-type" you want, for only that one invocation:

getPrivateTokenHeaders({contentType: 'graphql'});

Note: If you're using TypeScript, then you can improve the typing experience.

Development and production bundles

React Storefront Kit has a development bundle and a production bundle. The development bundle has warnings and messages that the production bundle doesn't.

Depending on the bundler or runtime that you're using, the correct bundle might be automatically chosen following the package.json#exports of React Storefront Kit. If not, then you might need to configure your bundler / runtime to use the development and production conditions.

Note: The production bundle is used by default if your bundler / runtime doesn't understand the export conditions.

React Storefront Kit in the browser

React Storefront Kit has a development umd build and a production umd build. Both are meant to be used directly either by <script src=""></script> tags in HTML or by AMD-compatible loaders.

If you're using React Storefront Kit as a global through the <script> tag, then the components can be accessed through the storefrontkitreact global variable.

Enable Storefront API GraphQL autocompletion

To improve your development experience, enable GraphQL autocompletion for the Storefront API in your integrated development environment (IDE).

Add graphql and GraphQL-config with the following command:
```
yarn add --dev graphql graphql-config
```
Create a GraphQL config file at the root of your code. For example, .graphqlrc.yml.

Add a schema and point it to React Storefront Kit's bundled schema for the Storefront API.

For example:

# Filename: .graphqlrc.yml
schema: node_modules/@shopify/storefront-kit-react/storefront.schema.json

Install a GraphQL extension in your IDE, such as the GraphQL extension for VSCode.

GraphQL autocompletion and validation will now work in .graphql files and in gql template literals!

If you're having trouble getting it to work, then consult our troubleshooting section.

TypeScript

Improve your development experience by using Storefront Kit's generated Types and helpers.

Storefront API types

Storefront Kit ships with generated TypeScript types that match the Storefront API and its objects. Import them from the /storefront-api-types package path:

import type {Product} from '@shopify/hydrogen-react/storefront-api-types';

const product: Product = {};

You can also use TypeScript's built-in helpers to create your own Types to fit your needs:

const partialProduct: Partial<Product> = {};

const productTitle: Pick<Product, 'title'> = '';

const productExceptTitle: Omit<Product, 'title'> = {};

GraphQL CodeGen

To use GraphQL CodeGen, follow their guide to get started. Then, when you have a codegen.ts file, you can modify the following lines in the codegen object to improve the CodgeGen experience:

import {storefrontApiCustomScalars} from '@shopify/storefront-kit-react';

const config: CodegenConfig = {
  // Use the schema that's bundled with @shopify/storefront-kit-react
  schema: './node_modules/@shopify/storefront-kit-react/storefront.schema.json',
  generates: {
    './gql/': {
      preset: 'client',
      plugins: [],
      config: {
        // Use the custom scalar definitions that @shopify/storefront-kit-react provides to improve the types
        scalars: storefrontApiCustomScalars,
      },
    },
  },
};

The `StorefrontApiResponseError` and `StorefrontApiResponseOk` helpers

The following is an example:

import {
  type StorefrontApiResponseError,
  type StorefrontApiResponseOk,
} from '@shopify/storefront-kit-react';

async function FetchApi<DataGeneric>() {
  const apiResponse = await fetch('...');

  if (!apiResponse.ok) {
    // 400 or 500 level error
    return (await apiResponse.text()) as StorefrontApiResponseError; // or apiResponse.json()
  }

  const graphqlResponse: StorefrontApiResponseOk<DataGeneric> =
    await apiResponse.json();

  // You can now access 'graphqlResponse.data' and 'graphqlResponse.errors'
}