# `@gadgetinc/shopify-extensions` 

This package provides a set of utilities to help you build Shopify extensions. Extensions for Shopify API version `2025-10` are written in Preact. Extensions on previous API versions are written in either React or JavaScript/Typescript. All languages are supported.

View the package on [npm](https://www.npmjs.com/package/@gadgetinc/shopify-extensions) and [GitHub](https://github.com/gadget-inc/js-clients/tree/main/packages/shopify-extensions).

## 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
yarn config set @gadget-client:registry https://registry.gadget.dev/npm

yarn add @gadget-client/example-app
```

```npm

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](https://docs.gadget-canary.xyz/api/example-app/development/external-api-calls/installing).

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

```yarn
yarn add @gadgetinc/shopify-extensions
```

```npm
npm install --save @gadgetinc/shopify-extensions
```

## Usage 

### Preact extensions 

Within a Shopify Preact 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/preact` path.

```preact
import "@shopify/ui-extensions/preact";
import { render } from "preact";
import { Provider, useGadget } from "@gadgetinc/shopify-extensions/preact";
import { ExampleAppClient } from "@gadget-client/example-app";

const gadgetApi = new ExampleAppClient();

export default async () => {
  render(<GadgetUIExtension />, document.body);
};

function GadgetUIExtension() {
  const { sessionToken } = shopify;
  return (
    <Provider api={gadgetApi} sessionToken={sessionToken}>
      <Extension />
    </Provider>
  );
}

function Extension() {
  // @type {{ ready: boolean, api: typeof apiClient }}
  const { api, ready } = 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/preact

  return <s-banner>Hello, world</s-banner>;
}
```

### JS/TS Extensions 

Within a JS/TS-only extension you can set up your Gadget client to authenticate with a session token:

```typescript
import { extension, Button } from "@shopify/ui-extensions/customer-account";
import { ExampleAppClient } from "@gadget-client/example-app";
import { registerShopifySessionTokenAuthentication } from "@gadgetinc/shopify-extensions";

const gadgetApi = new ExampleAppClient();

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.

```tsx
import { ExampleAppClient } 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 ExampleAppClient();

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 />);
```

## 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