BigCommerce App Extensions 

BigCommerce App Extensions allow developers to extend the control panel's capabilities by registering custom menu items that appear on select native control panel pages.

When a control panel user clicks an App Extension-generated menu item, the app can either render content in a side panel without navigating the user away from the native page, or it can redirect the user to the app's home iframe in the Apps sub-menu, and render App Extension-specific content there.

Your Gadget frontend routes can be used to power App Extensions.

Adding a new App Extension 

To add a new App Extension to a Gadget app:

Step 1: Set up a BigCommerce connection 

Set up a BigCommerce connection in Gadget and install on a BigCommerce sandbox store. Make sure that the App Extensions : manage OAuth scope is selected when setting up the connection. You don't need to worry about subscribing to webhooks at this time.

Step 2: Add a field to track the App Extension ID 

Add an appExtensionId string field to your bigcommerce/store model.

Step 3: Register the App Extension with the store on install 

Paste the following code into api/models/bigcommerce/store/install.js to create a new App Extension and save the App Extension ID to your bigcommerce/store model when your app is installed on a store.

Make sure to update the input variable of the GraphQL mutation to match the type of App Extension you want to create:

api/models/bigcommerce/store/install.js
JavaScript
Copy
1import {
2  applyParams,
3  save,
4  ActionOptions,
5  InstallBigcommerceStoreActionContext,
6} from "gadget-server";
7
8/**
9 * @param { InstallBigcommerceStoreActionContext } context
10 */
11export async function run({ params, record, logger, api, connections }) {
12  applyParams(params, record);
13  await save(record);
14}
15
16/**
17 * @param { InstallBigcommerceStoreActionContext } context
18 */
19export async function onSuccess({ params, record, logger, api, connections }) {
20  // use fetch for GraphQL request (GraphQL not supported by built-in client)
21  const response = await fetch(
22    `https://api.bigcommerce.com/stores/${record.storeHash}/graphql`,
23    {
24      method: "POST",
25      headers: {
26        "Content-Type": "application/json",
27        Accept: "application/json",
28        "X-Auth-Token": record.accessToken,
29      },
30      body: JSON.stringify({
31        query: `mutation AppExtension($input: CreateAppExtensionInput!) {
32        appExtension {
33          createAppExtension(input: $input) {
34            appExtension {
35              id
36              context
37              model
38              url
39              label {
40                defaultValue
41                locales {
42                  value
43                  localeCode
44                }
45              }
46            }
47          }
48        }
49      }`,
50        variables: {
51          // edit input to match your desired App Extension
52          input: {
53            context: "PANEL",
54            model: "PRODUCTS",
55            url: "/products/${id}/interactions",
56            label: {
57              defaultValue: "Interactions",
58              locales: [
59                {
60                  value: "Interaction Notes",
61                  localeCode: "en-US",
62                },
63                {
64                  value: "Notas de interacción",
65                  localeCode: "es-MX",
66                },
67              ],
68            },
69          },
70        },
71      }),
72    }
73  );
74
75  const jsonResponse = await response.json();
76
77  if (jsonResponse.errors) {
78    logger.error({ errors: jsonResponse.errors }, "Error creating app extension");
79  }
80
81  // save the App Extension id to your bigcommerce/store model
82  await api.internal.bigcommerce.store.update(record.id, {
83    appExtensionId:
84      jsonResponse.data.appExtension.createAppExtension.appExtension.id,
85  });
86}
87
88/** @type { ActionOptions } */
89export const options = {
90  actionType: "create",
91};

Step 4: Set up frontend routing 

Add a new file to your web/routes folder and add a route to your router in web/components/App.jsx.

For example, if you used the above example for your App Extension and set the url to /products/${id}/interactions, you would need to add the following to your route definition in web/components/App.jsx:

web/components/App.jsx
React
Copy
1import AppExtension from "../routes/appExtension";
2
3// ... other imports
4
5function App() {
6  // add route to router definition
7  const router = createBrowserRouter(
8    createRoutesFromElements(
9      <Route path="/" element={<Layout />}>
10        {/** ... existing routes */}
11        <Route path="/products/:productId/interactions" element={<AppExtension />} />
12      </Route>
13    )
14  );
15
16  return <RouterProvider router={router} />;
17}
18
19// ... more code

Then create a new file at web/routes/appExtension.js and build your App Extension UI:

web/routes/appExtension.jsx
React
Copy
1import { Panel, Text } from "@bigcommerce/big-design";
2import { useParams } from "react-router-dom";
3
4export default function () {
5  // useParams hook to get route param from BigCommerce
6  const { productId } = useParams();
7
8  return (
9    <>
10      <Panel description="Successfully created an App Extension!">
11        <Text>This extension is for product {productId}!</Text>
12      </Panel>
13    </>
14  );
15}

The useParams hook is used to grab the productId included in the route path.

Step 5: Test your App Extension 

Once you finish adding your routes and the custom backend code, you need to:

• Uninstall your app from the sandbox.
• Delete the existing bigcommerce/store record from the Gadget database. This can be done on the bigcommerce/store model's data page: api/models/bigcommerce/store/data.
• Install your app back on the sandbox.

This will run your GraphQL mutation on install and register the App Extension.

Now you can navigate to your App Extension and start building.

For more information on building frontends, read the single-click app frontend docs.