Calling your Gadget API from BigCommerce Catalyst storefronts 

Catalyst is BigCommerce's composable, fully customizable headless ecommerce storefront framework built on top of Next.js.

You can install your Gadget app's API client into your Catalyst storefront projects to read and write data from your Gadget app.

Installing your API client 

To install your Gadget app's API client into a Catalyst project, you need to follow the installation instructions in your app's API docs and install the client in the /core directory.

pnpm install @gadget-client/example-app

Once your client is installed, you can create a gadget.ts file in your core/ directory, and initialize your client:

import { Client } from "@gadget-client/@gadget-client/example-app";

export const api = new Client();

Now you can import api into your Catalyst project files and call your actions.

Calling your Gadget actions 

Because Catalyst is built with Next.js and the Next app router, the custom storefront will be server-side rendered. This means that data read using your Gadget API client can be done on the server, and favours the imperative API client calls instead of using the @gadgetinc/react hooks that are helpful when building SPAs (single-page applications).

For example, if you wanted to call a Gadget action to load data for a Catalyst product page:

1. You can add a function to a product/[slug]/page-data.ts file that calls your Gadget action.

1import { api } from "../../../../../gadget";
2
3// .. other imports
4// .. other functions
5
6export const loadCustomData = async () => {
7  const customData = await api.myCustomAction();
8  return customData;
9};

1import { api } from "../../../../../gadget";
2
3// .. other imports
4// .. other functions
5
6export const loadCustomData = async () => {
7  const customData = await api.myCustomAction();
8  return customData;
9};

2. In the product page you can call the loadCustomData function to call the Gadget API:

1// .. imports
2
3// .. data load + transform functions
4
5export default async function Product({ params: { locale, slug }, searchParams }: Props) {
6  // .. other data loading
7
8  const customData = await loadCustomData();
9
10  return (
11    <>
12      {/** other components */}
13
14      <div className="lg:col-span-2">
15        <b>{customData.foo}</b>
16      </div>
17
18      {/** other components */}
19    </>
20  );
21}
22
23export const runtime = "edge";

1// .. imports
2
3// .. data load + transform functions
4
5export default async function Product({ params: { locale, slug }, searchParams }: Props) {
6  // .. other data loading
7
8  const customData = await loadCustomData();
9
10  return (
11    <>
12      {/** other components */}
13
14      <div className="lg:col-span-2">
15        <b>{customData.foo}</b>
16      </div>
17
18      {/** other components */}
19    </>
20  );
21}
22
23export const runtime = "edge";

Using this configuration, data will be fetched from Gadget as part of the initial server-side request for the product page.

Permissions 

When you use an API client installed in Catalyst to call your Gadget actions, the default access control role granted to requests will be unauthenticated. This is typically okay for requests made from the storefront, as most shoppers will be unauthenticated while browsing.

Customer login 

If you are looking to provide logged-in shoppers an authenticated role with which to make requests to your Gadget backend, you will need to add custom code to support customer login in Catalyst, and manage token passing between your Catalyst storefront and your Gadget backend for all authenticated requests.