@gadgetinc/shopify-extensions 

This package provides a set of utilities to help you build Shopify extensions. Extensions written in either React or JavaScript/Typescript are supported.

View the package on npm and GitHub.

Installation 

This is a companion package to the JavaScript API 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:

yarn config set @gadget-client:registry https://registry.gadget.dev/npm

yarn add @gadget-client/example-app

npm config set @gadget-client:registry https://registry.gadget.dev/npm

npm install @gadget-client/example-app

Full installation instructions can be found in your app's API docs.

Once you have your JS client installed, you can install the @gadgetinc/shopify-extensions package:

yarn add @gadgetinc/shopify-extensions

npm install --save @gadgetinc/shopify-extensions

Usage 

JS/TS Extensions 

Within a JS/TS-only extension 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/example-app";
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  // helper function registers the session token with the API client
10  registerShopifySessionTokenAuthentication(gadgetApi, sessionToken);
11  // write the rest of your extension as you normally would
12  root.appendChild(
13    root.createComponent(
14      Button,
15      { to: "extension:/" },
16      i18n.translate("menuItemButton")
17    )
18  );
19});

1import { extension, Button } from "@shopify/ui-extensions/customer-account";
2import { Client } from "@gadget-client/example-app";
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  // helper function registers the session token with the API client
10  registerShopifySessionTokenAuthentication(gadgetApi, sessionToken);
11  // write the rest of your extension as you normally would
12  root.appendChild(
13    root.createComponent(
14      Button,
15      { to: "extension:/" },
16      i18n.translate("menuItemButton")
17    )
18  );
19});

React extensions 

Within a Shopify React extension, you must wrap your extension in a Provider component to provide the API client and session token to the rest of your extension.

You can then use useGadget to access your API client that has been setup for Shopify session token authentication.

Note that React helpers are imported using the @gadgetinc/shopify-extensions/react path.

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

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

Reference 

registerShopifySessionTokenAuthentication() 

registerShopifySessionTokenAuthentication(api: Client, sessionToken: SessionToken)

Registers the session token with the API client for use with Shopify session token authentication for JS/TS extensions.

Parameters 

• api: Client - The Gadget API client to use for the extension
• sessionToken: SessionToken - The session token to use for authentication

Provider 

A Provider component that wraps your React extension to provide the API client and session token to the rest of your extension.

Props 

• api: Client - The Gadget API client to use for the extension
• sessionToken: SessionToken - The session token to use for authentication

useGadget() 

useGadget(): { ready: boolean, api: Client }

A React hook that returns the Gadget API client and a boolean indicating whether the client is ready to authenticate with Shopify session token authentication.

Returns 

• api: Client - The Gadget API client that can be used to make API calls in an extension
• ready: boolean - A boolean indicating whether the client is ready to authenticate with Shopify session token authentication