@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:

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

npm install @gadget-client/example-app

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

yarn add @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:

npm install --save @gadgetinc/shopify-extensions

yarn add @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});

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

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