# Shopify app frontends 

Gadget offers a comprehensive toolkit for quickly constructing frontends for Shopify Apps. When connecting a Gadget app to Shopify, it automatically includes a basic, hosted frontend powered by Vite. This frontend comes preloaded with support for OAuth, Shopify's Polaris design system, multi-tenant data security, and integration with Shopify's App Bridge for embedded applications. You have the flexibility to customize this frontend according to your preferences, or you can create an entirely new external frontend from scratch using Gadget's React packages.

Frontends for Shopify apps interact with Gadget backends through the GraphQL API specific to your Gadget app, along with the corresponding JavaScript client for your application. To work with Gadget from a Shopify app frontend, there are several npm packages that are essential:

| Package | Description | Available from |
| --- | --- | --- |
| `@shopify/app-bridge` | Shopify's React package for embedding React applications within the Shopify Admin | [npm](https://www.npmjs.com/package/@shopify/app-bridge) |
| `@gadget-client/example-app` | The JS client for your specific Gadget application | [Gadget NPM registry](https://docs.gadget-canary.xyz/api/example-app/development/installing) |
| `@gadgetinc/react` | The Gadget React bindings library, providing React hooks for making API calls | [npm](https://www.npmjs.com/package/@gadgetinc/react) |
| `@gadgetinc/react-shopify-app-bridge` | The Gadget Shopify wrapper library for Shopify Embedded App setup and authentication | [npm](https://www.npmjs.com/package/@gadgetinc/react-shopify-app-bridge) |

Gadget installs these packages into your Gadget-hosted frontend automatically, but if you're building an [external frontend](https://docs.gadget-canary.xyz/guides/frontend/external-frontends) you must install them yourself.

Once you've set up your [Shopify connection](https://docs.gadget-canary.xyz/guides/plugins/shopify), your Gadget app will have a built-in frontend ready for construction in your app's `frontend` folder. This frontend can access data from your backend, including both models synced from Shopify and models created within your application. By default, your app uses React and Shopify's standard `@shopify/app-bridge-react` library, so Shopify's normal helpers for navigation and data fetching are ready for use as well.

Gadget frontends for Shopify include Shopify's design system Polaris via the `@shopify/polaris` package as well, so your app is compliant with Shopify's App Store guidelines out of the box.

If you'd like to build your frontend outside of Gadget, refer to the [external frontends](https://docs.gadget-canary.xyz/guides/frontend/external-frontends) guide.

## Reading data from your backend 

To facilitate easy access to data from your Gadget application, including both the non-rate-limited copies of Shopify models and your custom models, you can leverage the @gadgetinc/react hooks library in your frontend. This library provides a set of hooks, such as `useFindOne`, `useFindMany`, and `useFindFirst`, specifically designed for fetching data from your Gadget app.

When utilizing these hooks, each one returns an object that includes the requested data, the current fetching state, and an error object if any error occurred during the data retrieval process. Additionally, the returned object includes a refetch function that allows you to refresh the data if needed.

By using the provided hooks from the `@gadgetinc/react` library, you can easily fetch and manage data from your Gadget app within your frontend code. These hooks simplify the process of data retrieval, provide relevant states and error handling, and offer a convenient mechanism for refreshing the data when necessary.

For example, if you have the **Shopify Product** model enabled in your Connection, we can fetch product records in a variety of ways:

```typescript
// fetch one product by id
const [{ data, fetching, error }, refetch] = useFindOne(api.shopifyProduct, "10");
```

```typescript
// fetch the first 10 products
const [{ data, fetching, error }, refetch] = useFindMany(api.shopifyProduct, {
  first: 10,
});
```

```typescript
// fetch the first product with the title field equal to "Socks", throw if it isn't found
const [{ data, fetching, error }, refetch] = useFindFirst(api.shopifyProduct, {
  where: { title: "Socks" },
});
```

```typescript
// fetch the first product with the title field equal to "Socks", return null if it isn't found
const [{ data, fetching, error }, refetch] = useMaybeFindFirst(api.shopifyProduct, {
  where: { title: "Socks" },
});
```

Data from other models that you've created in your application is accessed the same way. For example, if we're building a free shipping banner app, you might create a **Banner** model that stores details about each shipping banner created. We can fetch banner records with the same React hooks:

```typescript
// fetch one banner by id
const [{ data, fetching, error }, refetch] = useFindOne(api.banner, "10");
```

```typescript
// fetch the first 10 banners
const [{ data, fetching, error }, refetch] = useFindMany(api.banner, { first: 10 });
```

Each of these hooks must be wrapped in a React component to render. For example, we can use `useFindMany` to display a list of products in a component:

```tsx
import { useFindMany } from "@gadgetinc/react";
import { api } from "../api";

export const ProductsList = () => {
  const [{ data, fetching, error }, _refetch] = useFindMany(api.shopifyProduct, {
    first: 10,
  });

  if (fetching || !data) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <ul>
      {data.map((product) => (
        <li key={product.id}>{product.title}</li>
      ))}
    </ul>
  );
};
```

For more on reading data in the frontend, see the [building frontends](https://docs.gadget-canary.xyz/guides/frontend) guide and the [@gadgetinc/react reference](https://docs.gadget-canary.xyz/reference/react).

### Shopify permissions 

Gadget incorporates multi-tenant data permissions as the default configuration for your application. By default, an app loaded for a specific Shopify shop can only access data within that particular shop and is not authorized to access data from other shops. This default setup utilizes the **Shopify App User role** for enforcing these permissions, and you have the flexibility to customize the permissions for this role on the Roles & Permissions page.

In Gadget, multi-tenant data permissions are automatically enforced for Shopify models. However, access to your own models is not automatically granted. To enable frontend access to your models, you need to assign permissions to the **Shopify App User** role for each model you wish to make accessible. For instance, if you want to access a model named Banner, you can navigate to the Roles & Permissions screen and select the Read permission checkbox for the Banner model.

For further guidance and details on managing access control, refer to the [access control guide](https://docs.gadget-canary.xyz/guides/access-control), which provides comprehensive information on configuring and customizing data permissions in Gadget.

## Writing data back to your backend 

Shopify app frontends can use the `useActionForm`, `useAction` and `useGlobalAction` hooks from the `@gadgetinc/react` hooks library to write data back to your database.

To update data within Shopify, you must make an API call to Shopify directly from your **backend**. See the  section for more information.

To write data back to your database for models you've created, or fields you've added to Shopify Models, use `useActionForm`, `useAction` or `useGlobalAction` hook in a React component.

For example, if we create a new model within our app called `banner`, we can use the `useActionForm` hook to create a form for new banner records:

```tsx
import { useActionForm } from "@gadgetinc/react";
import { api } from "../api";

export const CreateBannerForm = () => {
  const {
    register,
    submit,
    formState: { isSubmitting },
    error,
  } = useActionForm(api.banner.create);

  if (isSubmitting) {
    return <div>Saving...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <form onSubmit={submit}>
      <label>Message</label>
      <textarea {...register("message")} />
      <input type="submit" />
    </form>
  );
};
```

For more details on the `useActionForm` hook, see the `@gadgetinc/react` [reference](https://docs.gadget-canary.xyz/reference/react#useactionform), and see the [Building Frontends](https://docs.gadget-canary.xyz/guides/frontend/building-frontends#writing-data-to-models) guide for more examples.

## Calling Global Actions 

Shopify app frontends can call your backend's Global Actions with the `useGlobalAction` hook. See the [Building Frontends](https://docs.gadget-canary.xyz/guides/frontend/building-frontends#calling-global-actions) guide for more information.

## Calling HTTP routes 

Shopify app frontends can call your backend's HTTP Routes with `api.fetch`, or any other HTTP client for React. See the [Building Frontends](https://docs.gadget-canary.xyz/guides/frontend/building-frontends#calling-http-routes) guide for more information.

If your HTTP routes require authentication, or need to access the `connections` object server side, you _must_ ensure you pass the correct authentication headers to your HTTP route from your frontend. You can do this automatically by using `api.fetch` instead of the built-in browser `fetch`.  
  
For more information, see the [Building Frontends](https://docs.gadget-canary.xyz/guides/frontend/building-frontends#maintaining-session-state-when-calling-http-routes) guide.

## Calling the Shopify API 

In Gadget, it is generally recommended to read data through Gadget's API, as Gadget's API does not impose the same access restrictions as Shopify's API. Unlike Shopify's API, your Gadget app's API is not rate-limited, allowing you to fetch data without the need for meticulous request management.

However, if you require access to data that your Gadget app doesn't sync or if you need to retrieve data that Gadget doesn't have direct access to, you can utilize Shopify's API directly.

To make requests to Shopify's Admin API, it is best to initiate the calls from the backend of your Gadget app's API. This involves making a request from your frontend application to your Gadget backend, which in turn makes the necessary calls to Shopify's API. The results are then returned from your Gadget backend to your frontend application.

### Calling Shopify within actions 

Code within a [model actions](https://docs.gadget-canary.xyz/guides/actions) or [global actions](https://docs.gadget-canary.xyz/guides/actions#global-actions) can make API calls to Shopify using the `connections.shopify.current` Shopify API client Gadget provides.

For example, if we want to create a product from the frontend of our Gadget application, we can create an global action that calls the Shopify API:

First, we create a new global action called `createProduct.js` within the `api/actions` folder in Gadget.

Then, we can add the following code to the global action:

```typescript
export const run: ActionRun = async ({ logger, connections }) => {
  const shopify = connections.shopify.current;
  if (!shopify) {
    throw new Error("Missing Shopify connection");
  }

  const product = await shopify.graphql(
    `mutation ($input: ProductInput!) {
      productCreate(input: $input) {
        product {
          title
        }
      }
      userErrors {
        message
      }
    }`,
    {
      input: {
        title: "New Product",
      },
    }
  );
  logger.info({ product }, "created new product in shopify");
  return product;
};
```

This action uses Gadget's `connections` object to access the Shopify API client, and then calls the `product.create` method to create a new product in Shopify.

We can then call this global action from our Shopify frontend with the `useGlobalAction` React hook. For example, we can call this action when a button is clicked in the app:

```tsx
import { useGlobalAction } from "@gadgetinc/react";
import { api } from "../api";

export const CreateProductButton = () => {
  const [{ data, fetching, error }, createProduct] = useGlobalAction(api.createProduct);
  createProduct;

  return (
    <button disabled={fetching} onClick={() => void createProduct()}>
      Create Product
    </button>
  );
};
```

Gadget's synced Shopify models are one-way synced out of Shopify. You can't call the `api.shopifyProduct.create` action from the frontend to create a product, as that would put your Gadget app out of sync with Shopify. You must use the Shopify API to create resources that Shopify owns.

### Calling Shopify in HTTP Routes 

Route code within [HTTP Routes](https://docs.gadget-canary.xyz/guides/http-routes) can access the Shopify API using `request.connections.shopify` to create a Shopify API client object, similarly to Actions or Global Actions.

#### From authenticated API clients 

If you are calling your HTTP route from an API client that has been authenticated with a Shopify session token, for example, you are using `useFetch` inside your [embedded frontend](https://docs.gadget-canary.xyz/guides/frontend/building-frontends#maintaining-session-state-when-calling-http-routes), the value of `connections.shopify.current` can be used in the exact same way as you would from an action.

For example, an HTTP route could return an up-to-date list of products from the Shopify API:

```typescript
import { RouteHandler } from "gadget-server";

const route: RouteHandler = async ({ request, reply, api, logger, connections }) => {
  const shopify = connections.shopify.current;
  if (!shopify) {
    throw new Error("Missing Shopify connection");
  }

  const products = await shopify.graphql(
    `query {
      products(first: 10) {
        edges {
          node {
            id
            title
            handle
          }
          cursor
        }
        pageInfo {
          hasNextPage
        }
      }
    }`
  );

  await reply.send({
    products,
  });
};

export default route;
```

#### From unauthenticated API clients 

If you are calling your HTTP route from an unauthenticated API client, for example, from a [Shopify theme app extension](https://docs.gadget-canary.xyz/guides/plugins/shopify/advanced-topics/extensions#theme-app-extensions), the value of `connections.shopify.current` will not be set. Instead, you can use one of the following methods to create a Shopify API client object:

If your route has access to the shop id, you can use the `forShopId` method to create a Shopify API client object:

```typescript
import { RouteHandler } from "gadget-server";

const route: RouteHandler<{ Params: { shopId: string } }> = async ({
  request,
  reply,
  api,
  connections,
}) => {
  const { shopId } = request.params;
  const shopify = await connections.shopify.forShopId(shopId);

  const products = await shopify.graphql(
    `query {
      products(first: 10) {
        edges {
          node {
            id
            title
            handle
          }
          cursor
        }
        pageInfo {
          hasNextPage
        }
      }
    }`
  );

  await reply.send({
    products,
  });
};

export default route;
```

If your route has access to the shop domain, you can use the `forShopDomain` method to create a Shopify API client object:

```typescript
import { RouteHandler } from "gadget-server";

const route: RouteHandler<{ Params: { shopDomain: string } }> = async ({
  request,
  reply,
  api,
  connections,
}) => {
  const { shopDomain } = request.params;
  const shopify = await connections.shopify.forShopDomain(shopDomain);

  const products = await shopify.graphql(
    `query {
      products(first: 10) {
        edges {
          node {
            id
            title
            handle
          }
          cursor
        }
        pageInfo {
          hasNextPage
        }
      }
    }`
  );

  await reply.send({
    products,
  });
};

export default route;
```

Because the previous two methods need to make a database query to get the shop by id or domain, if you also need to load the shop record in your route, you can save a database query by using the `forShop` method:

```typescript
import { RouteHandler } from "gadget-server";

const route: RouteHandler<{ Params: { shopId: string } }> = async ({
  request,
  reply,
  api,
  connections,
}) => {
  const { shopId } = request.params;

  const shop = await api.internal.shopifyShop.findOne(shopId);
  // @ts-ignore
  const shopify = connections.shopify.forShop(shop);

  const products = await shopify.graphql(
    `query {
      products(first: 10) {
        edges {
          node {
            id
            title
            handle
          }
          cursor
        }
        pageInfo {
          hasNextPage
        }
      }
    }`
  );

  await reply.send({
    products,
  });
};

export default route;
```

When calling HTTP routes from an unauthenticated client, take care to ensure that you are [safe guarding sensitive data](https://docs.gadget-canary.xyz/guides/plugins/shopify/advanced-topics/data-security#safeguard-http-routes).

### Standalone Shopify Apps 

With a standalone Shopify app, you'll need to handle authentication and [tenancy](https://docs.gadget-canary.xyz/guides/plugins/shopify) yourself as there is no Shopify session token to derive this from.

If your Shopify app is not an embedded app, you can still use the Gadget [frontends](https://docs.gadget-canary.xyz/guides/frontend/building-frontends) to build your app. To do so, you will need to set the `type` prop on `GadgetProvider` to `AppType.Standalone`.

```tsx
export const App = () => {
  return (
    <GadgetProvider type={AppType.Standalone} shopifyApiKey={window.gadgetConfig.apiKeys.shopify} api={api}>
      <AuthenticatedApp />
    </GadgetProvider>
  );
};
```

## Shopify frontend security requirements 

Shopify requires app developers to meet a set of important security requirements when building embedded apps. Gadget meets each security requirement out of the box:

*   Gadget apps are always served over HTTPS
*   Gadget apps run behind a production-grade firewall and only expose the necessary services
*   Gadget apps use robust, multi-tenant authentication that limits access to data to the current shop (see the [access control](https://docs.gadget-canary.xyz/guides/access-control) guide)
*   Gadget sets up GDPR webhook listeners automatically for Shopify apps (see the [GDPR](https://docs.gadget-canary.xyz/guides/plugins/shopify#shopify-gdpr-request) docs)
*   Gadget uses Shopify's [Session Token](https://shopify.dev/docs/apps/auth/oauth/session-tokens) authentication mechanism for authenticating the frontend to the backend.
*   Gadget automatically sets the `Content-Security-Policy` header necessary for Shopify's IFrame protection when serving Shopify apps (see [Shopify's security docs](https://shopify.dev/docs/apps/store/security/iframe-protection))

If you have any questions about the security posture of Gadget applications for Shopify, please join us in our [Discord](https://ggt.link/discord) to discuss!

## Reference 

### The `Provider` 

The `@gadgetinc/react-shopify-app-bridge` library handles authentication of your embedded app via the `Provider` component. This provider has two main benefits - it handles authentication and the series of redirects required to complete an embedded app OAuth flow in Shopify, and it handles retrieving a Shopify session token from the App Bridge and passing it along to Gadget for authenticated calls.

The **Provider** handles these key tasks automatically:

*   Starts the OAuth process with new users of the application using Gadget, escaping Shopify's iframe if necessary
*   Establishes an iframe-safe secure session with the Gadget backend using Shopify's [Session Token](https://shopify.dev/apps/auth/oauth/session-tokens) authentication scheme
*   Sets up the correct React context for making backend calls to Gadget using `@gadgetinc/react`

The `Provider` has the following required props:

```typescript
export interface ProviderProps {
  type: AppType; // 'AppType.Embedded' or 'AppType.Standalone'
  shopifyApiKey: string; // the API key from your Shopify app in the Dev Dashboard that is used with the Shopify App Bridge
  api: string; // the API client created using your Gadget application
}
```

The Gadget provider will handle detecting if your app is being rendered in an embedded context and redirect the user through Shopify's OAuth flow if necessary.

### The `useGadget` React hook 

The `Provider` handles initializing the App Bridge for us. Now we can build our application component and use the initialized instance of App Bridge via the `appBridge` key returned from the embedded React hook `useGadget`.

`useGadget` provides the following properties:

### Using `Provider` and `useGadget` to set up App Bridge 

Here is an example of how to set up App Bridge, and use it to open an App Bridge resource picker:

```typescript
// import the Gadget<->Shopify bindings that manage the auth process with Shopify
import {
  AppType,
  Provider as GadgetProvider,
  useGadget,
} from "@gadgetinc/react-shopify-app-bridge";
// import the instance of the Gadget API client for this app constructed in the other file
import { api } from "../api";
// import the useGlobalAction hook to help call your Gadget API
import { useGlobalAction } from "@gadgetinc/react";

export default function App() {
  return (
    // Wrap our main application's react components in the `<GadgetProvider/>` component
    // to interface with Shopify. This wrapper sets up the Shopify App Bridge.
    // It will automatically redirect to perform the OAuth authentication
    // if the shopify shop doesn't yet have the store installed.
    <GadgetProvider
      type={AppType.Embedded}
      shopifyApiKey={window.gadgetConfig.apiKeys.shopify}
      api={api}
    >
      <SimplePage />
    </GadgetProvider>
  );
}

// An example component that uses the Gadget React hooks to work with data in the backend
function SimplePage() {
  const { loading, appBridge, isRootFrameRequest, isAuthenticated } = useGadget();

  // makeSelections is a global action in this example
  // it is called using Gadget's useGlobalAction hook
  const [{ error }, makeSelections] = useGlobalAction(api.makeSelections);

  return (
    <>
      {loading && <span>Loading...</span>}
      {/* A user is viewing this page from a direct link so show them the home page! */}
      {!loading && isRootFrameRequest && (
        <div>Welcome to my cool app's webpage!</div>
      )}
      {error && <div>{error.message}</div>}
      {!loading && isAuthenticated && (
        <button
          onClick={async () => {
            if (appBridge) {
              // open the App Bridge resource picker component
              const selected = appBridge.resourcePicker({ type: "product" });
              console.log({ selected });
              // pass selections to a global action
              await makeSelections({ selected });
            }
          }}
        >
          Open resource picker
        </button>
      )}
    </>
  );
}
```

Once `isAuthenticated` is `true`, you will be able to make authenticated API requests using your Gadget API client and the `@gadgetinc/react` hooks.

The `Provider` and `useGadget` are already set up for you when you connect to Shopify using Gadget's frontends.

### GraphQL queries 

When developing embedded Shopify apps, it is possible that the installed scopes of a Shop may not align with the required scopes in your Gadget app's connection. In such cases, it becomes necessary to re-authenticate with Shopify in order to obtain the updated scopes. To determine if re-authentication is required and gather information about missing scopes, you can execute the following GraphQL query using the app client provided to the `Provider`:

```graphql
query {
  shopifyConnection {
    requiresReauthentication
    missingScopes
  }
}
```

## **Session** model management 

The Shopify connection in Gadget automatically manages records of the backend **Session** model when using `@gadgetinc/react-shopify-app-bridge`. When a merchant first loads up the frontend application, the `<Provider/>` will retrieve a Shopify Session Token from Shopify's API, and pass it to your Gadget backend application. The Gadget Shopify connection will then validate this token. If valid, the connection will provision a new record of the **Session** model with the correct `shopId` field set up. This session is then passed to all your backend application's model filters and is available within Action code snippets.

## Embedded app examples 

Want to see an example of an embedded Shopify app built using Gadget?

Check out some of our [example apps on GitHub](https://github.com/gadget-inc/examples/tree/main/packages), including:

*   an [embedded NextJS application](https://github.com/gadget-inc/examples/tree/main/packages/nextjs-shopify)
*   an [embedded app built using the Shopify CLI](https://github.com/gadget-inc/examples/tree/main/packages/shopify-cli-embedded)

## External Frontends with the Shopify CLI 

If the built-in Gadget frontend doesn't work for you, you can use the frontend generated by the [Shopify CLI](https://shopify.dev/docs/apps/tools/cli) as an external frontend for your Gadget backend application. This lets you still take advantage of Gadget's OAuth handling, scalable backend database, and robust webhook processing while using the frontend generated by the Shopify CLI.

### Using the Shopify CLI frontend 

To use Shopify's generated frontend as an external frontend, you will need to make a few changes to the code generated by the Shopify CLI. Instead of deleting the `web` folder from your repository after generating a CLI app, keep it in place, and follow these steps:

*   Update `web/index.js` to not implement Shopify OAuth, as Gadget handles OAuth and syncing data from the Shopify API. Instead, `web/index.js` just needs to serve the frontend application with the correct security headers for Shopify.

Replace the contents of `web/index.js` with the following:

```typescript
import { join } from "path";
import * as fs from "fs";
import express, { Request, Response } from "express";
import serveStatic from "serve-static";

const __dirname = new URL(".", import.meta.url).pathname;

const PORT = parseInt(process.env["BACKEND_PORT"] || process.env["PORT"] || "0", 10);
const STATIC_PATH =
  process.env["NODE_ENV"] === "production"
    ? `${__dirname}/frontend/dist`
    : `${__dirname}/frontend/`;

const app = express();

// return Shopify's required iframe embedding headers for all requests
app.use((req, res, next) => {
  const shop = req.query.shop;
  if (shop) {
    res.setHeader(
      "Content-Security-Policy",
      `frame-ancestors https://${shop} https://admin.shopify.com;`
    );
  }
  next();
});

// serve any static assets built by vite in the frontend folder
app.use(serveStatic(STATIC_PATH, { index: false }));

// serve the client side app for all routes, allowing it to pick which page to render
app.use("/*", async (_req: Request, res: Response) => {
  res
    .status(200)
    .set("Content-Type", "text/html")
    .send(fs.readFileSync(join(STATIC_PATH, "index.html")));
});

app.listen(PORT);
```

*   You can then delete the other example code that `@shopify/cli` created in the `web/` directory when it created your app if you like by running the following command in your app's root directory

```shell
rm -f web/shopify.js web/product-creator.js web/gdpr.js
```

Finally, we can set up our Gadget Client and use the Provider to handle OAuth for our embedded app.

You need to install your Gadget dependencies in the `web/frontend` directory of your Shopify CLI application! Change into this directory before running the following commands:

```shell
cd web/frontend
```

*   Install `local-ssl-proxy` in the `web/frontend` directory

```npm
npm install local-ssl-proxy
```

```yarn
yarn add local-ssl-proxy
```

*   Update the `dev` script in `web/frontend/package.json` to `vite & local-ssl-proxy --source 443 --target 3005`.

```json
// in web/frontend/package.json
{
  // ...
  "scripts": {
    "build": "vite build",
    "dev": "vite & local-ssl-proxy --source 443 --target 3005",
    "coverage": "vitest run --coverage"
  }
}
```

If you are working with Windows, the `dev` command above will not work. You will need to split it up into two separate commands and run them separately. For example, `"dev": "vite"` and `"dev-proxy": "local-ssl-proxy --source 443 --target 3005"`.

This allows us to use our local frontend when doing development inside Shopify's admin, which uses HTTPS.

*   Replace your `web/frontend/vite.config` file with the following code:

```typescript
import { defineConfig } from "vite";
import { dirname } from "path";
import { fileURLToPath } from "url";
import react from "@vitejs/plugin-react";

if (
  process.env["npm_lifecycle_event"] === "build" &&
  !process.env["CI"] &&
  !process.env["SHOPIFY_API_KEY"]
) {
  console.warn(
    "\nBuilding the frontend app without an API key. The frontend build will not run without an API key. Set the SHOPIFY_API_KEY environment variable when running the build command.\n"
  );
}

const host = "localhost";
const port = 3005;

export default defineConfig({
  root: dirname(fileURLToPath(import.meta.url)),
  plugins: [react()],
  define: {
    "process.env": JSON.stringify({
      SHOPIFY_API_KEY: process.env["SHOPIFY_API_KEY"],
    }),
  },
  resolve: {
    preserveSymlinks: true,
  },
  server: {
    host,
    port,
    hmr: {
      protocol: "ws",
      host,
      port,
      clientPort: port,
    },
  },
});
```

If you wish to change the port for your local server, make sure to modify both the port variable in `web/frontend/vite.config` and the target at the end of the `dev` script in the `web/frontend/package.json`. Note that the ports must be the same for the proxy to function correctly.

Shopify CLI apps using Gadget don't need to use ngrok and instead run at `https://localhost`. This vite config keeps vite's hot module reloading functionality working quickly without using ngrok which is faster and more reliable.

*   You need to register the Gadget NPM registry for the `@gadget-client` package scope:

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

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

*   The following npm modules are required when creating an app that will be embedded in the Shopify Admin:

```npm
npm install @gadgetinc/react @gadgetinc/react-shopify-app-bridge @gadget-client/example-app
```

```yarn
yarn add @gadgetinc/react @gadgetinc/react-shopify-app-bridge @gadget-client/example-app
```

**Make sure to replace \`example-app\` with your app's package name!**

*   To deploy your frontend using hosting platforms such as [Vercel](https://docs.gadget-canary.xyz/guides/frontend/external-frontends#vercel), [Heroku](https://docs.gadget-canary.xyz/guides/frontend/external-frontends#heroku) or [Netlify](https://docs.gadget-canary.xyz/guides/frontend/external-frontends#netlify), you will need to add a new file `web/frontend/.npmrc` to help point to the Gadget registry.

*   The next step is to set up your Gadget client in the application. You can use this client to make requests to your Gadget application. You can create a new file in your project, and add the following code:

```typescript
import { ExampleAppClient } from "@gadget-client/example-app";

export const api = new ExampleAppClient();
```

*   Now you need to set up the Provider in `web/frontend/App.jsx`. We can also use the `useGadget` hook to ensure we are authenticated before we make requests using the API. Here is a small snippet as an example:

```tsx
import { AppType, Provider as GadgetProvider, useGadget } from "@gadgetinc/react-shopify-app-bridge";
import { api } from "./api";
import { PolarisProvider } from "./components";

/**
 * Gadget's Provider takes care of App Bridge authentication, you do not need Shopify's default AppBridgeProvider.
 */
export default function App() {
  return (
    <GadgetProvider type={AppType.Embedded} shopifyApiKey={process.env["SHOPIFY_API_KEY"]!} api={api}>
      <PolarisProvider>
        <EmbeddedApp />
      </PolarisProvider>
    </GadgetProvider>
  );
}

// This is where we make sure we have auth'd with AppBridge
// Once we have authenticated, we can render our app!
// Feel free to use the default page navigation that Shopify's CLI sets up for you
// example here - https://github.com/gadget-inc/examples/blob/main/packages/shopify-cli-embedded/web/frontend/App.jsx
function EmbeddedApp() {
  // we use `isAuthenticated` to render pages once the OAuth flow is complete!
  const { isAuthenticated } = useGadget();
  return isAuthenticated ? <span>Hello, world!</span> : <span>Authenticating...</span>;
}
```

If you are looking for examples of how to use our API client, visit our [examples repository](https://github.com/gadget-inc/examples).

### Next steps 

Once you've updated your Shopify CLI `web` folder to function as an external frontend, you can start building your app! See the [Shopify connection](https://docs.gadget-canary.xyz/guides/plugins/shopify) guide for more information on building apps for Shopify with Gadget.

### Deployment 

If using the Shopify CLI's `web` folder as the frontend for your application, you'll need to deploy it to a hosting platform. See the [External Frontends](https://docs.gadget-canary.xyz/guides/frontend/external-frontends) guide for more information on deploying your frontend elsewhere.

## Shopify App Bridge V4 support 

Gadget supports using Shopify's App Bridge V4, which is the first version from Shopify to use their new CDN-based delivery mechanism. Read more about the App Bridge in [Shopify's docs](https://shopify.dev/docs/api/app-bridge-library).

### Requirements 

When using version 4 of Shopify's App Bridge, applications must depend on 3 pieces:

*   a `<script/>` tag to import the code for the app bridge from Shopify's CDN (automatically added at runtime by Gadget)
*   the `@shopify/app-bridge-react` package from npm, version 4 or higher
*   the `@gadgetinc/react-shopify-app-bridge` package from npm, version `0.14` or higher

If you were previously using the `@shopify/app-bridge` package from npm, it must be removed.

### CDN Script Tag 

Shopify requires that the basic code for the app bridge is required from their CDN, instead of bundled into your application. This allows Shopify to ship changes to the app bridge like bug fixes and performance improvements without requiring you to redeploy your application. The CDN-based approach is what Shopify endorses, is required for the Built For Shopify badge, and the only version of the app-bridge still receiving updates. Gadget recommends adopting this CDN-based approach for all Shopify applications.

Gadget will automatically insert the `<script/>` tag to import the App Bridge from Shopify's CDN when using `@gadgetinc/react-shopify-app-bridge` version `0.14` or later.

### Upgrade procedure 

For existing apps on older versions who wish to upgrade, follow these steps:

1.  Upgrade the `@shopify/app-bridge-react` package to `4.x.x` by installing the latest version. For reference on using terminal commands within Gadget [check out our guide here](https://docs.gadget-canary.xyz/guides/development-tools/keyboard-shortcuts#command-palette).

```yarn
// in Run in the Gadget command palette

yarn upgrade @shopify/app-bridge-react@latest
```

2.  Upgrade the `@gadgetinc/react-shopify-app-bridge` package to `0.14.1` by installing the latest version.

```yarn
// in Run in the Gadget command palette

yarn upgrade @gadgetinc/react-shopify-app-bridge@latest
```

3.  Now remove `@shopify/app-bridge` dependency by uninstalling it.

```yarn
// in Run in the Gadget command palette

yarn remove @shopify/app-bridge
```

4.  Finally follow Shopify's guide [here on updating your components and hooks to work with Shopify App Bridge V4](https://shopify.dev/docs/api/app-bridge/migration-guide#step-4-update-components).

### Resulting code 

Each app's code for working with the new library may need to be different, depending on which hooks are being used. As an example, here's the base code for the `web/components/App.jsx` file for the new version of the Shopify App Bridge:

```typescript
import {
  AppType,
  Provider as GadgetProvider,
} from "@gadgetinc/react-shopify-app-bridge";
import { NavMenu } from "@shopify/app-bridge-react";
import { Page, Text } from "@shopify/polaris";
import { Link, Outlet } from "react-router";
import { api } from "../api";

function Layout() {
  return (
    <GadgetProvider
      type={AppType.Embedded}
      shopifyApiKey={window.gadgetConfig.apiKeys.shopify}
      api={api}
    >
      <AuthenticatedApp />
    </GadgetProvider>
  );
}

function EmbeddedApp() {
  return (
    <>
      <Outlet />
      <NavMenu>
        <Link to="/" rel="home">
          Shop Information
        </Link>
      </NavMenu>
    </>
  );
}

function UnauthenticatedApp() {
  return (
    <Page title="App">
      <Text variant="bodyMd" as="p">
        App can only be viewed in the Shopify Admin.
      </Text>
    </Page>
  );
}
```

If `main.jsx` still references `BrowserRouter`, it should be removed as it will not be compatible with `RouterProvider` in `App.jsx`