This package provides a set of utilities to help you build Shopify extensions. Extensions written in either React or JavaScript/Typescript are supported.
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:
Install the JS client for your app
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
Once you have your JS client installed, you can install the @gadgetinc/shopify-extensions package:
Install @gadgetinc/shopify-extensions
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:
Working in a JS/TS extension
JavaScript
import { extension, Button } from "@shopify/ui-extensions/customer-account";
import { Client } from "@gadget-client/example-app";
import { registerShopifySessionTokenAuthentication } from "@gadgetinc/shopify-extensions";
const gadgetApi = new Client();
export default extension("example.extension.point", (root, api) => {
const { i18n, sessionToken } = api;
// helper function registers the session token with the API client
registerShopifySessionTokenAuthentication(gadgetApi, sessionToken);
// write the rest of your extension as you normally would
root.appendChild(
root.createComponent(
Button,
{ to: "extension:/" },
i18n.translate("menuItemButton")
)
);
});
import { extension, Button } from "@shopify/ui-extensions/customer-account";
import { Client } from "@gadget-client/example-app";
import { registerShopifySessionTokenAuthentication } from "@gadgetinc/shopify-extensions";
const gadgetApi = new Client();
export default extension("example.extension.point", (root, api) => {
const { i18n, sessionToken } = api;
// helper function registers the session token with the API client
registerShopifySessionTokenAuthentication(gadgetApi, sessionToken);
// write the rest of your extension as you normally would
root.appendChild(
root.createComponent(
Button,
{ to: "extension:/" },
i18n.translate("menuItemButton")
)
);
});
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.
Working in a React extension
React
import { Client } from "@gadget-client/example-app";
import { Provider, useGadget } from "@gadgetinc/shopify-extensions/react";
import { reactExtension, useApi } from "@shopify/ui-extensions-react/customer-account";
const gadgetApi = new Client();
const GadgetUIExtension = () => {
const { sessionToken } = useApi();
return (
<Provider api={gadgetApi} sessionToken={sessionToken}>
<UIExtension />
</Provider>
);
};
function UIExtension() {
const { ready, api } = useGadget();
// ready will be true as soon as the api client is ready to authenticate with shopify session token auth
// use api as you normally would with @gadgetinc/react
return <></>;
}
export default reactExtension("example.extension.point", () => <GadgetUIExtension />);
import { Client } from "@gadget-client/example-app";
import { Provider, useGadget } from "@gadgetinc/shopify-extensions/react";
import { reactExtension, useApi } from "@shopify/ui-extensions-react/customer-account";
const gadgetApi = new Client();
const GadgetUIExtension = () => {
const { sessionToken } = useApi();
return (
<Provider api={gadgetApi} sessionToken={sessionToken}>
<UIExtension />
</Provider>
);
};
function UIExtension() {
const { ready, api } = useGadget();
// ready will be true as soon as the api client is ready to authenticate with shopify session token auth
// use api as you normally would with @gadgetinc/react
return <></>;
}
export default reactExtension("example.extension.point", () => <GadgetUIExtension />);
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