React Storefront Kit

Use React Storefront Kit to build a custom storefront in any third-party, React-based framework such as Next.js or Remix.

The following diagram illustrates two example custom storefront stacks. The first uses the Hydrogen framework, and the other uses a third-party framework with React Storefront Kit:

All Shopify app templates already have OAuth implemented. To save time and keep your app secure, Shopify recommends using an app template if possible.

To make it easier to query the Storefront API, React Storefront Kit includes a Storefront client that exposes a helper function called createStorefrontClient(). The client can take in delegate and public access tokens for making authenticated and unauthenticated requests to the Storefront API, respectively.

The Storefront client takes in your delegate access token with the following:

For handling buyer requests, the Storefront client includes the Shopify-Storefront-Buyer-IP header with the following:

There are some cases when the API request isn't on behalf of a buyer, such as during a static site build, where the header isn't needed.

The Storefront client takes in your public access token as an X-Shopify-Storefront-Access-Token on all queries that originate from a buyer client with the following:

And then:

Hydrogen and other authenticated Storefront API access should only use IP's for buyerIp that you trust. If the server is behind a trusted proxy, then that means using the proxy's X-Forwarded-For value. You should only use a request's X-Forwarded-For to set buyerIp if you trust the proxy that's setting X-Forwarded-For.

If the server is connecting to clients, for example buyer browsers directly, then it should use the IP of the request. If a server uses X-Forwarded-For in these instances, then malicious clients can spoof values for X-Forwarded-For and get around Shopify's bot protection. This results in Shopify rate limiting all requests from the server rather than just the requests that originate from bots.

• You're familiar with API authentication.

• You can make an authenticated request to the Admin API for an access token.

• You've retrieved a parent access token for the Admin API, which you can use to request a delegate access token for server requests.

• You've set the parent access token to offline.

Get started with React Storefront Kit by installing the package, importing the feature that you want to use in your app, and authenticating the Storefront API client so that you can make requests.

1. Run one of the following commands to install the package:

2. Import the component, hook, or utility that you want to use in your Hydrogen app. Refer to the list of what's available in React Storefront Kit.

To make requests to the Storefront API, you can use the following access tokens, which you request from the Admin API (GraphQL or REST):

• Delegate: Authenticated. Used for requests from a server or other private context. Set as privateStorefrontToken.

• Public: Unauthenticated. Used for requests from a browser or other public context. Set as publicStorefrontToken.

The following example requests a delegate access token. To request a public access token, make a request to the GraphQL Admin API's storefrontAccessTokenCreate mutation or make a POST request to the REST Admin API's StorefrontAccessToken resource.

1. Request a token from the REST Admin or GraphQL Admin API.

   The following example requests the access token with write_orders access scope and sets the expiry.

2. Add the delegate access token to the createStorefrontClient() helper function.

   The following is an example:

3. Use the delegate access token in your server-side queries.

   The following is an example using NextJS's getServerSideProps:

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:

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

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

• Consult the React Storefront Kit README for information on development and production bundles, React Storefront Kit in the browser, and improving your development experience by enabling GraphQL autocompletion and setting TypeScript types.