Introduction

This library is a collection of helpers for using your Gadget app in Shopify extensions. It works in both plain javascript extension contexts as well as with React.

Installation

This is a companion package to the JavaScript client package generated for your Gadget app. You must first install the JS client for your app, and then install this package.

To install the JS client for your app, you must set up the Gadget NPM registry, and then install the client:

1npm config set @gadget-client:registry https://registry.gadget.dev/npm
2
3yarn add @gadget-client/my-app-slug
4# or
5npm install @gadget-client/my-app-slug

Full installation instructions can be found in the Gadget docs at https://docs.gadget.dev/api/<my-app-slug>/external-api-calls/installing.

Once you have your JS client installed, you can install this library with yarn or npm:

yarn add @gadgetinc/shopify-extensions
# or
npm install --save @gadgetinc/shopify-extensions

Example usage

Within an extension function you can set up your Gadget client to authenticate with a session token:

1import { extension, Button } from "@shopify/ui-extensions/customer-account";
2import { Client } from "@gadget-client/my-app-slug";
3import { registerShopifySessionTokenAuthentication } from "@gadgetinc/shopify-extensions";
4
5const gadgetApi = new Client();
6
7export default extension("example.extension.point", (root, api) => {
8  const { i18n, sessionToken } = api;
9
10  registerShopifySessionTokenAuthentication(gadgetApi, sessionToken);
11
12  root.appendChild(root.createComponent(Button, { to: "extension:/" }, i18n.translate("menuItemButton")));
13});

Within a Shopify React extension, you can use useGadget to access your api client setup for shopify session token authentication:

1import { Client } from "@gadget-client/my-app-slug";
2import { Provider, useGadget } from "@gadgetinc/shopify-extensions/react";
3import { reactExtension, useApi } from "@shopify/ui-extensions-react/customer-account";
4
5const api = new Client();
6
7export default reactExtension("example.extension.point", () => <GadgetUIExtension />);
8
9function GadgetUIExtension() {
10  const { sessionToken } = useApi();
11
12  return (
13    <Provider api={api} sessionToken={sessionToken}>
14      <UIExtension />
15    </Provider>
16  );
17}
18
19function UIExtension() {
20  const { ready, api } = useGadget();
21
22  // ready will be true as soon as the api client is ready to authenticate with shopify session token auth
23  // use api as you normally would with @gadgetinc/react
24}