Use BigCommerce App Extensions to build a size chart app for Catalyst storefronts
Expected time: 30 minutes
This tutorial will show you how to build a size chart app for BigCommerce Catalyst storefronts, using App Extensions.
By the end of this tutorial, you will have:
- Set up a BigCommerce connection
- Stored BigCommerce data in a Gadget database
- Subscribed to BigCommerce webhooks and synced historical data
- Built a BigCommerce App Extension
- Set up a Catalyst storefront that reads size chart info from your Gadget app
Prerequisites
Before starting, you will need:
- A BigCommerce partner account
- A BigCommerce sandbox store
- A BigCommerce Catalyst project set up locally
Step 1: Create a new Gadget app and connect to BigCommerce
You will start by creating a new Gadget app and connecting to BigCommerce.
- Create a new Gadget app at gadget.new, select the BigCommerce app type, and give your app a name.
- Click the Connect to BigCommerce button on your app's home page.
- Create a new BigCommerce app in the BigCommerce Developer Portal.
- Copy the Auth callback URL and Load callback URL from Gadget to your BigCommerce app.
- Select the Products Read-only and App Extensions Manage OAuth scopes and click Update & Close in the BigCommerce app.
- In the BigCommerce Developer Portal, click View Client ID for your new app and copy the Client ID and Client Secret to Gadget, then click Continue.
- In your BigCommerce sandbox store, navigate to Apps → My Draft Apps, hover over your newly added app, click Learn more.
- Click Install.
You now have a full-stack, single-click BigCommerce app in your store control panel. OAuth and frontend sessions are handled, and you can subscribe to BigCommerce webhooks.
Step 2: Add a product data model
You need to store both product data and size charts created by merchants in your Gadget database. You can create data models in Gadget to store this data.
- Right-click on the
api/models/bigcommercedirectory in the Gadget file tree and select Add model. - Name the model
productand add the following fields and validations:
| Field name | Field type | Validations |
|---|---|---|
name | string | Required |
sizeChart | json | |
store | belongs to | Required |
bigcommerceId | number | Uniqueness (scoped by store), Required |
When a model is created and edited Gadget will automatically run the required mutations on the underlying database. A CRUD API will also be automatically generated for your model. Read more about data models in Gadget.
- For the
storefield, select thebigcommerce/storemodel as the parent model, so thatbigcommerce/storehas manybigcommerce/product.
bigcommerceId uniqueness validation
For multi-tenant apps, you may have multiple stores whose resources have the same bigcommerceId. To avoid conflicts, you can scope the
Uniqueness validation on bigcommerceId by the store relationship. This ensures that bigcommerceId is unique per store. Read more
about multi-tenancy in BigCommerce apps.
Step 3: Add appExtensionId field to bigcommerce/store
You also want to store the App Extension ID on your bigcommerce/store model so the extension can be referenced from your app.
Add the following field at api/models/bigcommerce/store/schema:
| Field name | Field type |
|---|---|
appExtensionId | string |
Step 4: Subscribe to store/product webhooks
You can use webhooks to keep your product data in Gadget up to date with data in a store.
- Click the + button next to
api/actionsand enterbigcommerce/handleProductWebhooks.js. This creates abigcommercenamespace folder and your new action. - Click the + button in the action's Triggers card and select BigCommerce.
- Select the
store/product/created,store/product/updated, andstore/product/deletedwebhook scopes. - (Optional) Remove the Generated API endpoint trigger from the action.
Now this action will run anytime a product is created, updated, or deleted in BigCommerce.
When a product webhook is fired, you want to call the bigcommerce/product model's actions to create, update, or delete records in the Gadget database.
Notice that the upsert meta API is used to handle store/product/updated webhooks. This is
because the product may not yet exist in your database.
- Paste the following code in
api/actions/bigcommerce/handleProductWebhooks.js:
api/actions/bigcommerce/handleProductWebhooks.js
JavaScript
import { ActionOptions } from "gadget-server";
export const run: ActionRun = async ({ params, api, connections, trigger }) => {
// get the BigCommerce API client for the current store
const bigcommerce = connections.bigcommerce.current!;
if (trigger.type !== "bigcommerce_webhook") {
throw new Error("This action can only be triggered by a BigCommerce webhook");
}
// handle store/product/deleted webhooks
if (trigger.scope === "store/product/deleted") {
const productRecordToDelete = await api.bigcommerce.product.maybeFindFirst({
filter: { bigcommerceId: { equals: params.id } },
select: { id: true },
});
if (productRecordToDelete) {
// if it exists, delete it
await api.bigcommerce.product.delete(productRecordToDelete.id);
}
return;
}
// handle store/product/created and store/product/updated webhooks
// fetch the product data
const product = await bigcommerce.v3.get("/catalog/products/{product_id}", {
path: {
product_id: params.id,
},
});
if (!product) {
throw new Error("Product not found");
}
// upsert product data into the model
await api.bigcommerce.product.upsert({
bigcommerceId: product.id,
store: {
// get the bigcommerce/store id for the record stored in Gadget
_link: connections.bigcommerce.currentStoreId,
},
name: product.name,
on: ["bigcommerceId", "store"],
});
};
export const options: ActionOptions = {
triggers: {
api: false,
bigcommerce: {
webhooks: [
"store/product/created",
"store/product/updated",
"store/product/deleted",
],
},
},
};
import { ActionOptions } from "gadget-server";
export const run: ActionRun = async ({ params, api, connections, trigger }) => {
// get the BigCommerce API client for the current store
const bigcommerce = connections.bigcommerce.current!;
if (trigger.type !== "bigcommerce_webhook") {
throw new Error("This action can only be triggered by a BigCommerce webhook");
}
// handle store/product/deleted webhooks
if (trigger.scope === "store/product/deleted") {
const productRecordToDelete = await api.bigcommerce.product.maybeFindFirst({
filter: { bigcommerceId: { equals: params.id } },
select: { id: true },
});
if (productRecordToDelete) {
// if it exists, delete it
await api.bigcommerce.product.delete(productRecordToDelete.id);
}
return;
}
// handle store/product/created and store/product/updated webhooks
// fetch the product data
const product = await bigcommerce.v3.get("/catalog/products/{product_id}", {
path: {
product_id: params.id,
},
});
if (!product) {
throw new Error("Product not found");
}
// upsert product data into the model
await api.bigcommerce.product.upsert({
bigcommerceId: product.id,
store: {
// get the bigcommerce/store id for the record stored in Gadget
_link: connections.bigcommerce.currentStoreId,
},
name: product.name,
on: ["bigcommerceId", "store"],
});
};
export const options: ActionOptions = {
triggers: {
api: false,
bigcommerce: {
webhooks: [
"store/product/created",
"store/product/updated",
"store/product/deleted",
],
},
},
};
This will handle the product webhook topics and call the required bigcommerce/product action. The products in your Gadget database will now stay up to date with any BigCommerce stores that have installed your app.
Step 5: Sync product data and set up a BigCommerce App Extension
You still need a way to sync existing product data into your data models. You also need to set up a BigCommerce App Extension.
You can do both of these things together in the api/models/bigcommerce/store/actions/install.js action. This action is run immediately after your app is installed on store.
Start by creating another global action to handle the data sync using Gadget's built-in background actions.
- Create a new file
syncProducts.jsinapi/actions/bigcommerceand paste the following code:
api/actions/bigcommerce/syncProducts.js
JavaScript
import { ActionOptions } from "gadget-server";
export const run: ActionRun = async ({ params, api, connections }) => {
// set the batch size to 50 for bulk upsert
const BATCH_SIZE = 50;
if (!params.storeHash) {
throw new Error("Store hash is required");
}
const bigcommerce = await connections.bigcommerce.forStoreHash(params.storeHash);
// use the API client to fetch all products, and return
const products = await bigcommerce.v3.list(`/catalog/products`);
// get the id of the store record in Gadget db
const store = await api.bigcommerce.store.findFirst({
filter: {
storeHash: {
equals: params.storeHash,
},
},
select: {
id: true,
},
});
const productPayload = [];
// use a for await loop to iterate over the AsyncIterables, add to an array
for await (const product of products) {
productPayload.push({
// use bigcommerceId and store to identify unique records for upsert
on: ["bigcommerceId", "store"],
// store the BigCommerce ID
bigcommerceId: product.id,
// associate the product with the current store
store: {
_link: store.id,
},
name: product.name,
});
// enqueue 50 actions at a time
if (productPayload.length >= BATCH_SIZE) {
const section = productPayload.splice(0, BATCH_SIZE);
// bulk enqueue create action
await api.enqueue(api.bigcommerce.product.bulkUpsert, section, {
queue: { name: "product-sync" },
});
// delay for a second, don't exceed rate limits!
await new Promise((r) => setTimeout(r, 1000));
// ONLY SYNC 50 PRODUCTS FOR THE TUTORIAL
break;
}
}
// enqueue any remaining products
await api.enqueue(api.bigcommerce.product.bulkUpsert, productPayload, {
queue: { name: "product-sync" },
});
};
export const options: ActionOptions = {
// 15 minute timeout for the sync
timeoutMS: 900000,
};
// accept store hash as action param
export const params = {
storeHash: { type: "string" },
};
import { ActionOptions } from "gadget-server";
export const run: ActionRun = async ({ params, api, connections }) => {
// set the batch size to 50 for bulk upsert
const BATCH_SIZE = 50;
if (!params.storeHash) {
throw new Error("Store hash is required");
}
const bigcommerce = await connections.bigcommerce.forStoreHash(params.storeHash);
// use the API client to fetch all products, and return
const products = await bigcommerce.v3.list(`/catalog/products`);
// get the id of the store record in Gadget db
const store = await api.bigcommerce.store.findFirst({
filter: {
storeHash: {
equals: params.storeHash,
},
},
select: {
id: true,
},
});
const productPayload = [];
// use a for await loop to iterate over the AsyncIterables, add to an array
for await (const product of products) {
productPayload.push({
// use bigcommerceId and store to identify unique records for upsert
on: ["bigcommerceId", "store"],
// store the BigCommerce ID
bigcommerceId: product.id,
// associate the product with the current store
store: {
_link: store.id,
},
name: product.name,
});
// enqueue 50 actions at a time
if (productPayload.length >= BATCH_SIZE) {
const section = productPayload.splice(0, BATCH_SIZE);
// bulk enqueue create action
await api.enqueue(api.bigcommerce.product.bulkUpsert, section, {
queue: { name: "product-sync" },
});
// delay for a second, don't exceed rate limits!
await new Promise((r) => setTimeout(r, 1000));
// ONLY SYNC 50 PRODUCTS FOR THE TUTORIAL
break;
}
}
// enqueue any remaining products
await api.enqueue(api.bigcommerce.product.bulkUpsert, productPayload, {
queue: { name: "product-sync" },
});
};
export const options: ActionOptions = {
// 15 minute timeout for the sync
timeoutMS: 900000,
};
// accept store hash as action param
export const params = {
storeHash: { type: "string" },
};
When run, this will fetch all product data from a BigCommerce store and enqueue upserts using Gadget's background actions. Background actions are used so you get the built-in retry handling to ensure data is reliably added to your database in bulk.
This sample code will break the product iteration loop after 50 products this is to limit resources used while building this tutorial.
Remove the break in the snippet to sync all product data for production apps.
Now you can call your sync action and set up a BigCommerce App Extension in the install action.
You will provide a url for the App Extension that you will hook up to a frontend route soon: "/products/${id}/size-chart".
- Paste the following in
api/models/bigcommerce/store/actions/install.js:
api/models/bigcommerce/store/actions/install.js
JavaScript
import { applyParams, save, ActionOptions } from "gadget-server";
export const run: ActionRun = async ({ params, record }) => {
applyParams(params, record);
await save(record);
};
export const onSuccess: ActionOnSuccess = async ({
record,
logger,
api,
params,
}) => {
if (!params?.store?.storeHash) {
throw new Error("No store hash found, cannot install app");
}
// use internal API to read access token for app extension registration
const store = await api.internal.bigcommerce.store.findFirst({
filter: {
storeHash: { equals: params.store.storeHash },
},
select: {
accessToken: true,
},
});
// use fetch for GraphQL request (GraphQL not supported by built-in client)
const response = await fetch(
`https://api.bigcommerce.com/stores/${record.storeHash}/graphql`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
"X-Auth-Token": store.accessToken,
},
body: JSON.stringify({
query: `mutation AppExtension($input: CreateAppExtensionInput!) {
appExtension {
createAppExtension(input: $input) {
appExtension {
id
context
model
url
label {
defaultValue
locales {
value
localeCode
}
}
}
}
}
}`,
variables: {
// edit input to match your desired App Extension
input: {
context: "PANEL",
model: "PRODUCTS",
url: "/products/${id}/size-chart",
label: {
defaultValue: "Size chart",
locales: [
{
value: "Size chart",
localeCode: "en-US",
},
],
},
},
},
}),
}
);
const jsonResponse = await response.json();
if (jsonResponse.errors) {
logger.error({ errors: jsonResponse.errors }, "Error creating app extension");
}
// save the App Extension id to your bigcommerce/store model
await api.internal.bigcommerce.store.update(record.id, {
appExtensionId:
jsonResponse.data.appExtension.createAppExtension.appExtension.id,
});
// sync existing product data from BigCommerce store to Gadget db
// use background action so install is not blocked
await api.enqueue(api.bigcommerce.syncProducts, {
storeHash: record.storeHash,
});
};
export const options: ActionOptions = {
actionType: "create",
};
import { applyParams, save, ActionOptions } from "gadget-server";
export const run: ActionRun = async ({ params, record }) => {
applyParams(params, record);
await save(record);
};
export const onSuccess: ActionOnSuccess = async ({
record,
logger,
api,
params,
}) => {
if (!params?.store?.storeHash) {
throw new Error("No store hash found, cannot install app");
}
// use internal API to read access token for app extension registration
const store = await api.internal.bigcommerce.store.findFirst({
filter: {
storeHash: { equals: params.store.storeHash },
},
select: {
accessToken: true,
},
});
// use fetch for GraphQL request (GraphQL not supported by built-in client)
const response = await fetch(
`https://api.bigcommerce.com/stores/${record.storeHash}/graphql`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
"X-Auth-Token": store.accessToken,
},
body: JSON.stringify({
query: `mutation AppExtension($input: CreateAppExtensionInput!) {
appExtension {
createAppExtension(input: $input) {
appExtension {
id
context
model
url
label {
defaultValue
locales {
value
localeCode
}
}
}
}
}
}`,
variables: {
// edit input to match your desired App Extension
input: {
context: "PANEL",
model: "PRODUCTS",
url: "/products/${id}/size-chart",
label: {
defaultValue: "Size chart",
locales: [
{
value: "Size chart",
localeCode: "en-US",
},
],
},
},
},
}),
}
);
const jsonResponse = await response.json();
if (jsonResponse.errors) {
logger.error({ errors: jsonResponse.errors }, "Error creating app extension");
}
// save the App Extension id to your bigcommerce/store model
await api.internal.bigcommerce.store.update(record.id, {
appExtensionId:
jsonResponse.data.appExtension.createAppExtension.appExtension.id,
});
// sync existing product data from BigCommerce store to Gadget db
// use background action so install is not blocked
await api.enqueue(api.bigcommerce.syncProducts, {
storeHash: record.storeHash,
});
};
export const options: ActionOptions = {
actionType: "create",
};
This action:
- uses a GraphQL request to set up an App Extension
- stores the ID of the App Extension on the
bigcommerce/storemodel - kicks off a data sync by calling
api.syncProducts()
For more details on working with App Extensions in Gadget, read our docs.
Running the install action
You have already installed your app on a store. This means that to run this action you need to:
- uninstall the app from your sandbox store
- delete the store record in Gadget at
api/models/bigcommerce/store/data - reinstall the app on your sandbox store
Note: For production apps, you may want to run this same code in both the bigcommerce/store/install and bigcommerce/store/reinstall
actions.
Step 6: Access control
All Gadget apps have authorization built in. A role-based access control system allows us to restrict API and data access to merchants and shoppers.
The bigcommerce-app-users role is automatically assigned to merchants who install your app in BigCommerce. Storefront shoppers will be granted the unauthenticated role. You can read more about roles in our docs.
You need to grant both merchants and shoppers access to the actions that power size chart frontends:
- Navigate to the
accessControl/permissionspage. - Grant the
bigcommerce-app-usersrole access to thebigcommerce/product/model'sreadandupdateactions. This will allow merchants to create and save size charts for products. - Grant the
unauthenticatedrole access to thebigcommerce/productmodel'sreadAPI. This allows shoppers to read the size charts in a storefront.
Read our data security and multi-tenancy docs to learn how to secure your actions when building apps that will be installed on multiple stores.
Step 7: App Extension Size Chart code
Now you are ready to build your App Extension frontend. Gadget frontends are built with React and all code is located in the web folder. BigDesign has also been installed for you.
An API client has been set up for you in web/api.js. While you build, and add model and actions to your app, Gadget will keep this client up to date. You will use this client, along with React hooks from the @gadgetinc/react package, to call your actions and save changes to size charts.
Start by adding a new route component to your frontend. The next step will be defining this route on the frontend router.
- Create a new file
size-chart.jsxinweb/routesand paste the following code:
web/routes/size-chart.jsx
React
import { Box, Button, Flex, FlexItem, Form, H2, Input, Message, Panel, StatefulTable, Text } from "@bigcommerce/big-design";
import { AddIcon, RemoveIcon } from "@bigcommerce/big-design-icons";
import { useAction, useFindFirst } from "@gadgetinc/react";
import { ChangeEvent, FormEvent, memo, useCallback, useEffect, useMemo, useState } from "react";
import { useParams } from "react-router";
import { api } from "../api";
// sample data used when no size chart is present
const SAMPLE_COLUMNS = [{ hash: "column1" }, { hash: "column2" }, { hash: "column3" }, { hash: "column4" }];
const SAMPLE_ITEMS = [
{
id: "header",
column1: "Size",
column2: "S",
column3: "M",
column4: "L",
},
{
id: "row1",
column1: "Chest",
column2: '34-36"',
column3: '37-38"',
column4: '39-40"',
},
{
id: "row2",
column1: "Waist",
column2: '30-32"',
column3: '33-34"',
column4: '35-36"',
},
];
// buttons for adding or removing columns and rows to table
const TableButtons = ({
name,
onAdd,
onRemove,
disableRemove,
}: {
name: string;
onAdd: () => void;
onRemove: () => void;
disableRemove: boolean;
}) => (
<Flex style={{ width: "250px", padding: "10px" }} flexDirection="row" justifyContent="space-between" alignItems="center">
<FlexItem flexShrink={1}>
<Text>{name}</Text>
</FlexItem>
<FlexItem>
<Flex flexDirection="row" alignItems="center" style={{ gap: "4px" }}>
<FlexItem>
<Button iconOnly={<RemoveIcon title="remove" />} onClick={() => onRemove()} disabled={disableRemove} type="button" />
</FlexItem>
<FlexItem>
<Button iconOnly={<AddIcon title="add" />} onClick={() => onAdd()} type="button" />
</FlexItem>
</Flex>
</FlexItem>
</Flex>
);
// memoized cell that can be edited
const EditableCell = memo(({ initialValue, onSave }: { initialValue: string; onSave: (value: string) => void }) => {
const [value, setValue] = useState(initialValue);
const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
setValue(e.target.value);
};
const handleBlur = () => {
if (value !== initialValue) {
onSave(value);
}
};
return <Input type="text" value={value} onChange={handleChange} onBlur={handleBlur} />;
});
// the actual size chart
const SizeChart = ({
product,
isErrorVisible,
setIsErrorVisible,
}: {
product: {
bigcommerceId: string;
id: string;
name: string;
sizeChart?: {
items: any[];
columns: any[];
};
};
isErrorVisible: boolean;
setIsErrorVisible: (value: boolean) => void;
}) => {
// call Gadget action to save size chart
const [{ data: savedChart, fetching: savingChart, error: chartSaveError }, saveSizeChart] = useAction(api.bigcommerce.product.update);
// state for the chart (in BigDesign StatefulTable input format)
const [columns, setColumns] = useState(product.sizeChart?.columns || SAMPLE_COLUMNS);
const [items, setItems] = useState(product.sizeChart?.items || SAMPLE_ITEMS);
// state for managing error and success message visibility
const [isSaveVisible, setIsSaveVisible] = useState(false);
// manage message visibility
useEffect(() => {
if (!savingChart && savedChart) {
setIsSaveVisible(true);
}
}, [savingChart, savedChart]);
useEffect(() => {
if (chartSaveError) {
setIsErrorVisible(true);
}
}, [chartSaveError]);
// update state when a cell is edited
const handleCellChange = useCallback((itemId: string, columnHash: string, value: string) => {
setItems((prevItems) => prevItems.map((item) => (item.id === itemId ? { ...item, [columnHash]: value } : item)));
if (itemId === "header") {
setColumns((prevColumns) => prevColumns.map((col) => (col.hash === columnHash ? { ...col, header: value } : col)));
}
}, []);
// render editable (and memoized) cells
const renderCell = (handler: typeof handleCellChange) => (column: { hash: string }) => {
return ({ [column.hash]: value, id }: { [key: string]: string }) => (
<EditableCell key={`${id}-${column.hash}`} initialValue={value || ""} onSave={(newValue) => handler(id, column.hash, newValue)} />
);
};
// memoized cells prevent re-renders of the whole table when state is updated
const memoizedRenderCell = useCallback(renderCell(handleCellChange), [handleCellChange]);
// columns rendered in the table
const tableColumns = useMemo(
() =>
columns.map((column) => ({
...column,
render: memoizedRenderCell(column),
})),
[columns, memoizedRenderCell]
);
// callback for adding a new column
// edit column and item state
const addColumn = useCallback(() => {
const newColumnHash = `column${columns.length + 1}`;
setColumns((prevColumns) => [...prevColumns, { hash: newColumnHash }]);
setItems((prevItems) =>
prevItems.map((item) => ({
...item,
[newColumnHash]: "",
}))
);
}, [columns.length]);
// callback for removing a new column
// edit column and item state
const removeColumn = useCallback(() => {
if (columns.length > 2) {
const updatedColumns = [...columns];
const removedColumn = updatedColumns.pop();
setColumns(updatedColumns);
setItems((prevItems) => prevItems.map(({ [removedColumn.hash]: _, ...rest }) => rest));
}
}, [columns]);
// edit item state when a row is added
const addRow = useCallback(() => {
const newRow = {
id: `row${items.length}`,
...Object.fromEntries(columns.map((col) => [col.hash, ""])),
};
setItems((prevItems) => [...prevItems, newRow]);
}, [columns, items.length]);
// edit item state when a row is removed
const removeRow = useCallback(() => {
if (items.length > 2) {
setItems((prevItems) => prevItems.slice(0, -1));
}
}, [items.length]);
// save the chart
const onSubmit = useCallback(
async (event: FormEvent<HTMLFormElement>) => {
event.preventDefault();
setIsSaveVisible(false);
await saveSizeChart({
id: product.id,
sizeChart: { columns, items },
});
},
[items]
);
return (
<>
<H2>Size chart for {product.name}</H2>
{!product.sizeChart && !savedChart && <Text>Sample chart provided. Make edits and save.</Text>}
{isSaveVisible && <Message header="Success" onClose={() => setIsSaveVisible(false)} messages={[{ text: "Size chart saved" }]} />}
{isErrorVisible && (
<Message
header="Error on save"
type="error"
messages={[
{
text: `Error: ${chartSaveError?.message}`,
},
]}
onClose={() => setIsErrorVisible(false)}
/>
)}
<Form onSubmit={onSubmit}>
<StatefulTable columns={tableColumns} items={items} keyField="id" headerless />
<Box marginTop="medium">
<TableButtons name="Columns" onAdd={addColumn} onRemove={removeColumn} disableRemove={columns.length <= 2} />
<TableButtons name="Rows" onAdd={addRow} onRemove={removeRow} disableRemove={items.length <= 2} />
</Box>
<Box marginTop="medium">
<Button type="submit" disabled={savingChart}>
Save chart
</Button>
</Box>
</Form>
</>
);
};
export default function () {
const params = useParams();
const productId = params.productId!;
const [isErrorVisible, setIsErrorVisible] = useState(false);
const [{ data: product, fetching, error }] = useFindFirst(api.bigcommerce.product, {
select: { id: true, name: true, sizeChart: true },
filter: { bigcommerceId: { equals: parseInt(productId) } },
});
if (!product) {
return <Text>Product not found</Text>;
}
return (
<Panel>
{error && (
<Message
header="Error fetching chart"
type="error"
messages={[
{
text: `Error: ${error.message}`,
},
]}
onClose={() => setIsErrorVisible(false)}
/>
)}
{fetching ? (
<Text>Loading...</Text>
) : (
<SizeChart
product={{
bigcommerceId: productId,
id: product.id,
name: product.name,
sizeChart: product.sizeChart as any,
}}
isErrorVisible={isErrorVisible}
setIsErrorVisible={setIsErrorVisible}
/>
)}
</Panel>
);
}
import { Box, Button, Flex, FlexItem, Form, H2, Input, Message, Panel, StatefulTable, Text } from "@bigcommerce/big-design";
import { AddIcon, RemoveIcon } from "@bigcommerce/big-design-icons";
import { useAction, useFindFirst } from "@gadgetinc/react";
import { ChangeEvent, FormEvent, memo, useCallback, useEffect, useMemo, useState } from "react";
import { useParams } from "react-router";
import { api } from "../api";
// sample data used when no size chart is present
const SAMPLE_COLUMNS = [{ hash: "column1" }, { hash: "column2" }, { hash: "column3" }, { hash: "column4" }];
const SAMPLE_ITEMS = [
{
id: "header",
column1: "Size",
column2: "S",
column3: "M",
column4: "L",
},
{
id: "row1",
column1: "Chest",
column2: '34-36"',
column3: '37-38"',
column4: '39-40"',
},
{
id: "row2",
column1: "Waist",
column2: '30-32"',
column3: '33-34"',
column4: '35-36"',
},
];
// buttons for adding or removing columns and rows to table
const TableButtons = ({
name,
onAdd,
onRemove,
disableRemove,
}: {
name: string;
onAdd: () => void;
onRemove: () => void;
disableRemove: boolean;
}) => (
<Flex style={{ width: "250px", padding: "10px" }} flexDirection="row" justifyContent="space-between" alignItems="center">
<FlexItem flexShrink={1}>
<Text>{name}</Text>
</FlexItem>
<FlexItem>
<Flex flexDirection="row" alignItems="center" style={{ gap: "4px" }}>
<FlexItem>
<Button iconOnly={<RemoveIcon title="remove" />} onClick={() => onRemove()} disabled={disableRemove} type="button" />
</FlexItem>
<FlexItem>
<Button iconOnly={<AddIcon title="add" />} onClick={() => onAdd()} type="button" />
</FlexItem>
</Flex>
</FlexItem>
</Flex>
);
// memoized cell that can be edited
const EditableCell = memo(({ initialValue, onSave }: { initialValue: string; onSave: (value: string) => void }) => {
const [value, setValue] = useState(initialValue);
const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
setValue(e.target.value);
};
const handleBlur = () => {
if (value !== initialValue) {
onSave(value);
}
};
return <Input type="text" value={value} onChange={handleChange} onBlur={handleBlur} />;
});
// the actual size chart
const SizeChart = ({
product,
isErrorVisible,
setIsErrorVisible,
}: {
product: {
bigcommerceId: string;
id: string;
name: string;
sizeChart?: {
items: any[];
columns: any[];
};
};
isErrorVisible: boolean;
setIsErrorVisible: (value: boolean) => void;
}) => {
// call Gadget action to save size chart
const [{ data: savedChart, fetching: savingChart, error: chartSaveError }, saveSizeChart] = useAction(api.bigcommerce.product.update);
// state for the chart (in BigDesign StatefulTable input format)
const [columns, setColumns] = useState(product.sizeChart?.columns || SAMPLE_COLUMNS);
const [items, setItems] = useState(product.sizeChart?.items || SAMPLE_ITEMS);
// state for managing error and success message visibility
const [isSaveVisible, setIsSaveVisible] = useState(false);
// manage message visibility
useEffect(() => {
if (!savingChart && savedChart) {
setIsSaveVisible(true);
}
}, [savingChart, savedChart]);
useEffect(() => {
if (chartSaveError) {
setIsErrorVisible(true);
}
}, [chartSaveError]);
// update state when a cell is edited
const handleCellChange = useCallback((itemId: string, columnHash: string, value: string) => {
setItems((prevItems) => prevItems.map((item) => (item.id === itemId ? { ...item, [columnHash]: value } : item)));
if (itemId === "header") {
setColumns((prevColumns) => prevColumns.map((col) => (col.hash === columnHash ? { ...col, header: value } : col)));
}
}, []);
// render editable (and memoized) cells
const renderCell = (handler: typeof handleCellChange) => (column: { hash: string }) => {
return ({ [column.hash]: value, id }: { [key: string]: string }) => (
<EditableCell key={`${id}-${column.hash}`} initialValue={value || ""} onSave={(newValue) => handler(id, column.hash, newValue)} />
);
};
// memoized cells prevent re-renders of the whole table when state is updated
const memoizedRenderCell = useCallback(renderCell(handleCellChange), [handleCellChange]);
// columns rendered in the table
const tableColumns = useMemo(
() =>
columns.map((column) => ({
...column,
render: memoizedRenderCell(column),
})),
[columns, memoizedRenderCell]
);
// callback for adding a new column
// edit column and item state
const addColumn = useCallback(() => {
const newColumnHash = `column${columns.length + 1}`;
setColumns((prevColumns) => [...prevColumns, { hash: newColumnHash }]);
setItems((prevItems) =>
prevItems.map((item) => ({
...item,
[newColumnHash]: "",
}))
);
}, [columns.length]);
// callback for removing a new column
// edit column and item state
const removeColumn = useCallback(() => {
if (columns.length > 2) {
const updatedColumns = [...columns];
const removedColumn = updatedColumns.pop();
setColumns(updatedColumns);
setItems((prevItems) => prevItems.map(({ [removedColumn.hash]: _, ...rest }) => rest));
}
}, [columns]);
// edit item state when a row is added
const addRow = useCallback(() => {
const newRow = {
id: `row${items.length}`,
...Object.fromEntries(columns.map((col) => [col.hash, ""])),
};
setItems((prevItems) => [...prevItems, newRow]);
}, [columns, items.length]);
// edit item state when a row is removed
const removeRow = useCallback(() => {
if (items.length > 2) {
setItems((prevItems) => prevItems.slice(0, -1));
}
}, [items.length]);
// save the chart
const onSubmit = useCallback(
async (event: FormEvent<HTMLFormElement>) => {
event.preventDefault();
setIsSaveVisible(false);
await saveSizeChart({
id: product.id,
sizeChart: { columns, items },
});
},
[items]
);
return (
<>
<H2>Size chart for {product.name}</H2>
{!product.sizeChart && !savedChart && <Text>Sample chart provided. Make edits and save.</Text>}
{isSaveVisible && <Message header="Success" onClose={() => setIsSaveVisible(false)} messages={[{ text: "Size chart saved" }]} />}
{isErrorVisible && (
<Message
header="Error on save"
type="error"
messages={[
{
text: `Error: ${chartSaveError?.message}`,
},
]}
onClose={() => setIsErrorVisible(false)}
/>
)}
<Form onSubmit={onSubmit}>
<StatefulTable columns={tableColumns} items={items} keyField="id" headerless />
<Box marginTop="medium">
<TableButtons name="Columns" onAdd={addColumn} onRemove={removeColumn} disableRemove={columns.length <= 2} />
<TableButtons name="Rows" onAdd={addRow} onRemove={removeRow} disableRemove={items.length <= 2} />
</Box>
<Box marginTop="medium">
<Button type="submit" disabled={savingChart}>
Save chart
</Button>
</Box>
</Form>
</>
);
};
export default function () {
const params = useParams();
const productId = params.productId!;
const [isErrorVisible, setIsErrorVisible] = useState(false);
const [{ data: product, fetching, error }] = useFindFirst(api.bigcommerce.product, {
select: { id: true, name: true, sizeChart: true },
filter: { bigcommerceId: { equals: parseInt(productId) } },
});
if (!product) {
return <Text>Product not found</Text>;
}
return (
<Panel>
{error && (
<Message
header="Error fetching chart"
type="error"
messages={[
{
text: `Error: ${error.message}`,
},
]}
onClose={() => setIsErrorVisible(false)}
/>
)}
{fetching ? (
<Text>Loading...</Text>
) : (
<SizeChart
product={{
bigcommerceId: productId,
id: product.id,
name: product.name,
sizeChart: product.sizeChart as any,
}}
isErrorVisible={isErrorVisible}
setIsErrorVisible={setIsErrorVisible}
/>
)}
</Panel>
);
}
This frontend route:
- gets the
productIdfrom the params - loads existing product data, including a size chart if it already exists
- renders a dynamic table component that can be customized
- cells are memoized to prevent redraws on
Inputupdates - state is managed with
useStatehooks
- cells are memoized to prevent redraws on
- saves a size chart as json by calling the
api.bigcommerce.product.updateaction
@gadgetinc/react hooks
Gadget provides the @gadgetinc/react library which contains useful hooks and tools for building React frontends. The
useFindMany, useAction, and useActionForm hooks are used to fetch data, call actions, and manage form state, respectively.
- Now add the route definition to the frontend router in
web/components/App.jsx:
web/components/App.jsx
React
// .. additional imports
import SizeChart from "../routes/size-chart";
// add the new route in the App component
function App() {
const router = createBrowserRouter(
createRoutesFromElements(
<Route path="/" element={<Layout />}>
<Route index element={<Index />} />
<Route path="*" element={<Error404 />} />
{/** add the size chart route */}
<Route path="/products/:productId/size-chart" element={<SizeChart />} />
</Route>
)
);
return <RouterProvider router={router} />;
}
// .. additional imports
import SizeChart from "../routes/size-chart";
// add the new route in the App component
function App() {
const router = createBrowserRouter(
createRoutesFromElements(
<Route path="/" element={<Layout />}>
<Route index element={<Index />} />
<Route path="*" element={<Error404 />} />
{/** add the size chart route */}
<Route path="/products/:productId/size-chart" element={<SizeChart />} />
</Route>
)
);
return <RouterProvider router={router} />;
}
Testing your App Extension
Now you can test your App Extension. Open up the Size chart extension for a product in your store.
Make sure you select one of the 50 products that was synced to your Gadget database. You can see what products were synced at api/models/bigcommerce/product/data.
You can modify the number of rows and columns in the chart, and edit the chart contents/measurements.
Once you are done, click Save chart and the chart config will be saved to Gadget as JSON.
Step 8: Draw size chart in Catalyst product page
The last step is rendering the custom size charts on the product pages of a Catalyst storefront.
You need to install a copy of your API client into your Catalyst project to read size chart data from your Gadget models.
Your API client package will have the format @gadget-client/<YOUR-APP-SLUG>.
- Set up a Catalyst project and start your dev server. This can be an existing storefront or a new project.
cdinto your Catalyst project'scorefolder.- Install your Gadget API client:
terminal
pnpm install @gadget-client/example-app
You may also need to register the Gadget NPM repository.
terminal
npm config set @gadget-client:registry https://registry.gadget.dev/npm
- Create a new file
gadget.tsincore/, then initialize and export your client:
core/gadget.ts
TypeScript
import { Client } from "@gadget-client/example-app";
export const api = new Client();
- Create a
size-chart.jsxfile incore/app/[locale]/(default)/product/[slug]/_componentsand paste the following code:
core/app/[locale]/(default)/product/[slug]/_components/size-chart.jsx
React
import React from "react";
import { api } from "../../../../../../gadget";
// Define types for the size chart data
interface SizeChartItem {
id: string;
[key: string]: string;
}
interface SizeChartData {
items: SizeChartItem[];
columns: { hash: string }[];
}
// SizeChart component
export const SizeChart: React.FC<{ productId: number }> = async ({ productId }) => {
// fetch size chart for product from Gadget API
const response = await api.bigcommerce.product.findFirst({
filter: {
bigcommerceId: {
equals: productId, // select the size chart for this product
},
store: {
storeHash: {
equals: process.env.BIGCOMMERCE_STORE_HASH, // for multi-tenant apps, select the size chart for this store
},
},
},
select: {
sizeChart: true, // only return the size chart field
},
});
const { sizeChart } = response.toJSON();
// no size chart available, return nothing!
if (!sizeChart) {
return null;
}
/// map json response to SizeChartData type
const data: SizeChartData = {
items: (sizeChart as any).items as SizeChartItem[],
columns: (sizeChart as any).columns as { hash: string }[],
};
return (
<>
<h2 className="mb-4 text-xl font-bold md:text-2xl">Size chart</h2>
<table className="table-auto border-collapse border border-gray-300">
<thead>
<tr>
{data.columns.map((column) => (
<th key={column.hash} className="border border-gray-300 p-2">
{data.items[0] && data.items[0][column.hash as keyof SizeChartItem]}
</th>
))}
</tr>
</thead>
<tbody>
{data.items.slice(1).map((item) => (
<tr key={item.id}>
{Object.entries(item)
.filter(([key, _value]) => key !== "id")
.map(([key, value], index) => (
<td key={`${key}_${index}`} className="border border-gray-300 p-2">
{value}
</td>
))}
</tr>
))}
</tbody>
</table>
</>
);
};
import React from "react";
import { api } from "../../../../../../gadget";
// Define types for the size chart data
interface SizeChartItem {
id: string;
[key: string]: string;
}
interface SizeChartData {
items: SizeChartItem[];
columns: { hash: string }[];
}
// SizeChart component
export const SizeChart: React.FC<{ productId: number }> = async ({ productId }) => {
// fetch size chart for product from Gadget API
const response = await api.bigcommerce.product.findFirst({
filter: {
bigcommerceId: {
equals: productId, // select the size chart for this product
},
store: {
storeHash: {
equals: process.env.BIGCOMMERCE_STORE_HASH, // for multi-tenant apps, select the size chart for this store
},
},
},
select: {
sizeChart: true, // only return the size chart field
},
});
const { sizeChart } = response.toJSON();
// no size chart available, return nothing!
if (!sizeChart) {
return null;
}
/// map json response to SizeChartData type
const data: SizeChartData = {
items: (sizeChart as any).items as SizeChartItem[],
columns: (sizeChart as any).columns as { hash: string }[],
};
return (
<>
<h2 className="mb-4 text-xl font-bold md:text-2xl">Size chart</h2>
<table className="table-auto border-collapse border border-gray-300">
<thead>
<tr>
{data.columns.map((column) => (
<th key={column.hash} className="border border-gray-300 p-2">
{data.items[0] && data.items[0][column.hash as keyof SizeChartItem]}
</th>
))}
</tr>
</thead>
<tbody>
{data.items.slice(1).map((item) => (
<tr key={item.id}>
{Object.entries(item)
.filter(([key, _value]) => key !== "id")
.map(([key, value], index) => (
<td key={`${key}_${index}`} className="border border-gray-300 p-2">
{value}
</td>
))}
</tr>
))}
</tbody>
</table>
</>
);
};
This component:
- uses your
apiclient to read product size chart data - renders a size chart, if data is returned from Gadget
- Import the
SizeChartcomponent into your product page atcore/app/[locale]/(default)/product/[slug]/page.tsxand render the chart:
core/app/[locale]/(default)/product/[slug]/page.jsx
React
// .. other imports
import { SizeChart } from "./_components/size-chart";
// .. interface, type, and function definitions
export default async function Product({ params: { locale, slug }, searchParams }: Props) {
return (
<>
{/* other components such as Breadcrumbs */}
<div className="mb-12 mt-4 lg:grid lg:grid-cols-2 lg:gap-8">
{/* other components such as Gallery and Details */}
<div className="lg:col-span-2">
<Description product={product} />
{/* other components such as Reviews */}
<Suspense fallback={t("loading")}>
<SizeChart productId={product.entityId} />
</Suspense>
</div>
</div>
{/* rest of the page */}
</>
);
}
// .. other imports
import { SizeChart } from "./_components/size-chart";
// .. interface, type, and function definitions
export default async function Product({ params: { locale, slug }, searchParams }: Props) {
return (
<>
{/* other components such as Breadcrumbs */}
<div className="mb-12 mt-4 lg:grid lg:grid-cols-2 lg:gap-8">
{/* other components such as Gallery and Details */}
<div className="lg:col-span-2">
<Description product={product} />
{/* other components such as Reviews */}
<Suspense fallback={t("loading")}>
<SizeChart productId={product.entityId} />
</Suspense>
</div>
</div>
{/* rest of the page */}
</>
);
}
For more information on building with Catalyst storefronts, read our docs.
Test it out
You have just built a full stack size chart app, congrats!
You can preview your custom size charts on the storefront by navigating to a product page for which you have built and saved a size chart.
Next steps
- Join Gadget's developer community on Discord
You can extend and customize this app. Some possibilities include:
- importing existing size charts as a CSV into your Gadget database using an action
- displaying the size chart in a model on the storefront