# Shopify App package for Remix

The [@shopify/shopify-app-remix](https://www.npmjs.com/package/@shopify/shopify-app-remix) package enables Remix apps to authenticate with Shopify and make API calls. It uses [App Bridge](https://shopify.dev/docs/api/app-bridge-library) to enable apps to embed themselves in the Shopify Admin.

In this page we'll go over the main components you need to integrate an app with Shopify.

## Quick start

The quickest way to create a new app is using the Shopify CLI. You can use your preferred package manager for that.

Check out the [getting started guide](https://shopify.dev/docs/apps/getting-started), or the [app template](https://github.com/Shopify/shopify-app-template-remix) for a complete example.
```sh
npm init @shopify/app@latest

```

```sh
yarn create @shopify/app

```

```sh
pnpm create @shopify/app

```

- [Navigate to](https://shopify.dev/docs/apps/getting-started/build-qr-code-app): Build an app

## Installation

If you're not using the CLI, then you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.
```sh
npm i --save @shopify/shopify-app-remix

```

```sh
yarn add @shopify/shopify-app-remix

```

```sh
pnpm add @shopify/shopify-app-remix

```


## Backend setup

Using the `shopifyApp` function, you can create an object that enables your app's backend to authenticate requests coming from Shopify, and interacting with Shopify APIs.

These functions make it easy for your app stays up to date, benefitting from the current best practices and security updates.

> Caution: When running on a node environment, you'll also need to import the node adapter, as per the example. This will ensure your app is using the appropriate implementation of the Web [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and [crypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) APIs.
```ts
import '@shopify/shopify-app-remix/server/adapters/node';
import {
  LATEST_API_VERSION,
  shopifyApp,
} from '@shopify/shopify-app-remix/server';

const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  appUrl: process.env.SHOPIFY_APP_URL!,
  scopes: ['read_products'],
  apiVersion: LATEST_API_VERSION,
});
export default shopify;

```

- [](https://shopify.dev/docs/api/shopify-app-remix/entrypoints/shopifyapp): shopifyApp

## Response headers

When loading inside the Shopify Admin, your app will need to add the required `Content-Security-Policy` header directives, as per [our documentation](https://shopify.dev/docs/apps/store/security/iframe-protection). To do that, this package provides the `shopify.addDocumentResponseHeaders` method.

You should return these headers from any endpoint that renders HTML in your app. Most likely you'll want to add this to every HTML response by updating the `entry.server.tsx` file:
```tsx
import shopify from './shopify.server';

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext,
) {
  shopify.addDocumentResponseHeaders(request, responseHeaders);

  // ..etc
}

```


## Error boundaries

The OAuth process can't happen inside the admin iframe, and this package is capable of detecting that scenario and properly redirecting using the [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors) export to set the correct headers for App Bridge.

Use the abstractions provided by this package in your authenticated routes, to automatically set up the error and headers boundaries to redirect outside the iframe when needed.

> Tip: You can also add this to a [Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2) if you want to authenticate more than one route, but make sure to call the Shopify boundary methods whenever you need to add your own exports.
```tsx
import {boundary} from '@shopify/shopify-app-remix/server';

export function ErrorBoundary() {
  return boundary.error(useRouteError());
}

export const headers = (headersArgs) => {
  return boundary.headers(headersArgs);
};

```


## OAuth route

> Tip: This is only applicable to non-embedded apps or legacy embedded apps that are **not** using the [new embedded app authorization strategy](#embedded-auth-strategy) for OAuth and installation flow. If you're building an embedded app, we **strongly** recommend using the [new embedded app authorization strategy](#embedded-auth-strategy)

To install an app or refresh tokens, you'll need to set up an [OAuth](docs/apps/auth/oauth) route. To do that, set up a [splat route](https://remix.run/docs/en/main/guides/routing#splats) that calls `authenticate.admin`.

When that function is called, the package will start the OAuth process, and handle the callback from Shopify after it completes.

The default route is `/app/routes/auth/$.tsx`, but you can configure this route using the `authPathPrefix` option.
```ts
import {LoaderFunctionArgs} from '@remix-run/node';

import shopify from '~/shopify.server';

export async function loader({request}: LoaderFunctionArgs) {
  await shopify.authenticate.admin(request);

  // App logic goes here

  return null;
}

```


## New embedded app authorization strategy

> Tip: This is available for embedded apps that are using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).
> If you're building an embedded app, we **strongly** recommend using this feature that utilizes Shopify managed install with [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange).

 We have introduced a new authorization and installation strategy for **embedded apps** that eliminates the redirects that were previously necessary. It replaces the legacy [authorization Code install and grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant).

It takes advantage of [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) to handle automatic app installations and scope updates, while using [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange) to get an access token for the logged-in user.

 If you wish to learn about scopes management and APIs, please read through [Manage access scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes)

 > Note: Newly created Remix apps from the template after February 1st 2024 has this feature enabled by default.

1. Enable [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) by configuring your scopes [through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration).
2. Enable the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file.
3. Enjoy no-redirect OAuth flow, and app installation process.
```ts
// ... imports
const shopify = shopifyApp({
  // .. and the rest of the config
  isEmbeddedApp: true,
  future: {
    unstable_newEmbeddedAuthStrategy: true,
  },
)};

// ... exports

```


## AppProvider

In order to use all of the features from App Bridge, you'll need to use the `AppProvider` component in your app's routes.

This component will set up App Bridge and Polaris so you can integrate your app into the Shopify Admin, and it helps us ensure your app stays up to date with Shopify requirements.

To do this pass the `process.env.SHOPIFY_API_KEY` to the frontend via the loader.
```tsx
import {LoaderFunctionArgs} from '@remix-run/node';
import {AppProvider} from '@shopify/shopify-app-remix/react';

import shopify from '~/shopify.server';

export async function loader({request}: LoaderFunctionArgs) {
  await shopify.authenticate.admin(request);

  return json({
    apiKey: process.env.SHOPIFY_API_KEY,
  });
}

export default function App() {
  const {apiKey} = useLoaderData<typeof loader>();

  return (
    <html>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <AppProvider apiKey={apiKey} isEmbeddedApp>
          <Outlet />
        </AppProvider>
      </body>
    </html>
  );
}

```

- [Learn more about App Bridge.](https://shopify.dev/docs/api/app-bridge-library): App bridge
- [Learn more about Polaris.](https://polaris.shopify.com): Polaris
- [](https://shopify.dev/docs/api/shopify-app-remix/entrypoints/appprovider): AppProvider

## References

- [AppProvider](https://shopify.dev/docs/api/shopify-app-remix/v1/entrypoints/appprovider.txt): Sets up the Polaris `AppProvider` and injects the App Bridge script.  This component extends the [`AppProvider`](https://polaris.shopify.com/components/utilities/app-provider) component from Polaris, and accepts all of its props except for `linkComponent`, which is overridden to use the Remix `Link` component.
- [Admin](https://shopify.dev/docs/api/shopify-app-remix/v1/authenticate/admin.txt): Contains functions for authenticating and interacting with the Admin API.  This function can handle requests for apps embedded in the Admin, Admin extensions, or non-embedded apps.
- [Billing](https://shopify.dev/docs/api/shopify-app-remix/v1/apis/billing.txt): Contains function used to bill merchants for your app.  This object is returned on authenticated Admin requests.
- [App proxy](https://shopify.dev/docs/api/shopify-app-remix/v1/authenticate/public/app-proxy.txt): The `authenticate.public.appProxy` function validates app proxy requests made by Shopify, and returns a context to enable querying Shopify APIs.
- [Checkout](https://shopify.dev/docs/api/shopify-app-remix/v1/authenticate/public/checkout.txt): The `authenticate.public.checkout` function ensures that checkout extension requests are coming from Shopify, and returns helpers to respond with the correct headers.
- [Webhook](https://shopify.dev/docs/api/shopify-app-remix/v1/authenticate/webhook.txt): Contains functions for verifying Shopify webhooks.
- [Admin API](https://shopify.dev/docs/api/shopify-app-remix/v1/apis/admin-api.txt): Contains objects used to interact with the Admin API.  This object is returned as part of different contexts, such as [`admin`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/admin), [`unauthenticated.admin`](https://shopify.dev/docs/api/shopify-app-remix/unauthenticated/unauthenticated-admin), and [`webhook`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/webhook).
- [Storefront API](https://shopify.dev/docs/api/shopify-app-remix/v1/apis/storefront-api.txt): Contains objects used to interact with the Storefront API.  This object is returned as part of different contexts, such as [`appProxy`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/public/app-proxy), and [`unauthenticated.storefront`](https://shopify.dev/docs/api/shopify-app-remix/unauthenticated/unauthenticated-storefront).
- [shopifyApp](https://shopify.dev/docs/api/shopify-app-remix/v1/entrypoints/shopifyapp.txt): Returns a set of functions that can be used by the app's backend to be able to respond to all Shopify requests.  The shape of the returned object changes depending on the value of `distribution`. If it is `AppDistribution.ShopifyAdmin`, then only `ShopifyAppBase` objects are returned, otherwise `ShopifyAppLogin` objects are included.
- [Unauthenticated admin](https://shopify.dev/docs/api/shopify-app-remix/v1/unauthenticated/unauthenticated-admin.txt): Allows interacting with the Admin API on requests that didn't come from Shopify.  > Caution: This should only be used for Requests that do not originate from Shopify. > You must do your own authentication before using this method. >This function doesn't perform **any** validation and shouldn't rely on unvalidated user input.
- [Unauthenticated storefront](https://shopify.dev/docs/api/shopify-app-remix/v1/unauthenticated/unauthenticated-storefront.txt): Allows interacting with the Storefront API on requests that didn't come from Shopify.  > Caution: This should only be used for Requests that do not originate from Shopify. > You must do your own authentication before using this method. >This function doesn't perform **any** validation and shouldn't rely on unvalidated user input.
- [AppProvider](https://shopify.dev/docs/api/shopify-app-remix/v2/entrypoints/appprovider.txt): Sets up the Polaris `AppProvider` and injects the App Bridge script.  This component extends the [`AppProvider`](https://polaris.shopify.com/components/utilities/app-provider) component from Polaris, and accepts all of its props except for `linkComponent`, which is overridden to use the Remix `Link` component.
- [AppProxyForm](https://shopify.dev/docs/api/shopify-app-remix/v2/app-proxy-components/appproxyform.txt): Sets up a Remix `<Form>` component that works when rendered behind an app proxy.  Supports any properties accepted by the `<Form>` component.
- [AppProxyLink](https://shopify.dev/docs/api/shopify-app-remix/v2/app-proxy-components/appproxylink.txt): Sets up an `<a />` HTML element that works when rendered behind an app proxy.  Supports any properties accepted by the `<a />` HTML element.
- [AppProxyProvider](https://shopify.dev/docs/api/shopify-app-remix/v2/entrypoints/appproxyprovider.txt): Sets up a page to render behind a Shopify app proxy, enabling JavaScript and CSS to be loaded from the app.  Also provides components that enable using other components such as links and forms within proxies.  > Caution: Because Remix doesn't support URL rewriting, any route using this component should <b>match the pathname of the proxy URL exactly</b>, and <b>end in a trailing slash</b> (e.g., `https://<shop>/apps/proxy/`).
- [Admin](https://shopify.dev/docs/api/shopify-app-remix/v2/authenticate/admin.txt): Contains functions for authenticating and interacting with the Admin API.  This function can handle requests for apps embedded in the Admin, Admin extensions, or non-embedded apps.
- [Billing](https://shopify.dev/docs/api/shopify-app-remix/v2/apis/billing.txt): Contains function used to bill merchants for your app.  This object is returned on authenticated Admin requests.
- [Flow](https://shopify.dev/docs/api/shopify-app-remix/v2/authenticate/flow.txt): Contains functions for verifying Shopify Flow extensions.  See the [Flow documentation](https://shopify.dev/docs/apps/flow/actions/endpoints) for more information.
- [Fulfillment Service](https://shopify.dev/docs/api/shopify-app-remix/v2/authenticate/fulfillment-service.txt): Contains functions for verifying fulfillment service requests.  See the [fulfillment service documentation](https://shopify.dev/docs/apps/fulfillment/fulfillment-service-apps) for more information.
- [App proxy](https://shopify.dev/docs/api/shopify-app-remix/v2/authenticate/public/app-proxy.txt): [App proxies](https://shopify.dev/docs/apps/online-store/app-proxies) take requests to Shopify links, and redirect them to external links. The `authenticate.public.appProxy` function validates requests made to app proxies, and returns a context to enable querying Shopify APIs.  > Note: If the store has not installed the app, store-related properties such as `admin` or `storefront` will be `undefined`
- [Checkout](https://shopify.dev/docs/api/shopify-app-remix/v2/authenticate/public/checkout.txt): The `authenticate.public.checkout` function ensures that checkout extension requests are coming from Shopify, and returns helpers to respond with the correct headers.
- [Webhook](https://shopify.dev/docs/api/shopify-app-remix/v2/authenticate/webhook.txt): Contains functions for verifying Shopify webhooks.  > Note: The format of the `admin` object returned by this function changes with the `v3_webhookAdminContext` future flag. Learn more about [gradual feature adoption](https://shopify.dev/docs/api/shopify-app-remix/guide-future-flags).
- [Admin API](https://shopify.dev/docs/api/shopify-app-remix/v2/apis/admin-api.txt): Contains objects used to interact with the Admin API.  This object is returned as part of different contexts, such as [`admin`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/admin), [`unauthenticated.admin`](https://shopify.dev/docs/api/shopify-app-remix/unauthenticated/unauthenticated-admin), and [`webhook`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/webhook).
- [Storefront API](https://shopify.dev/docs/api/shopify-app-remix/v2/apis/storefront-api.txt): Contains objects used to interact with the Storefront API.  This object is returned as part of different contexts, such as [`appProxy`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/public/app-proxy), and [`unauthenticated.storefront`](https://shopify.dev/docs/api/shopify-app-remix/unauthenticated/unauthenticated-storefront).
- [shopifyApp](https://shopify.dev/docs/api/shopify-app-remix/v2/entrypoints/shopifyapp.txt): Returns a set of functions that can be used by the app's backend to be able to respond to all Shopify requests.  The shape of the returned object changes depending on the value of `distribution`. If it is `AppDistribution.ShopifyAdmin`, then only `ShopifyAppBase` objects are returned, otherwise `ShopifyAppLogin` objects are included.
- [Unauthenticated admin](https://shopify.dev/docs/api/shopify-app-remix/v2/unauthenticated/unauthenticated-admin.txt): Allows interacting with the Admin API when working outside of Shopify requests. This enables apps to integrate with 3rd party services and perform background tasks.  > Caution: > This function doesn't perform **any** validation and shouldn't rely on raw user input.  When using this function, consider the following:  #### Background tasks  Apps should ensure that the shop domain is authenticated when enqueueing jobs.  #### 3rd party service requests  Apps must obtain the shop domain from the 3rd party service in a secure way.
- [Unauthenticated storefront](https://shopify.dev/docs/api/shopify-app-remix/v2/unauthenticated/unauthenticated-storefront.txt): Allows interacting with the Storefront API when working outside of Shopify requests. This enables apps to integrate with 3rd party services and perform background tasks.  > Caution: > This function doesn't perform **any** validation and shouldn't rely on raw user input.  When using this function, consider the following:  #### Background tasks  Apps should ensure that the shop domain is authenticated when enqueueing jobs.  #### 3rd party service requests  Apps must obtain the shop domain from the 3rd party service in a secure way.
- [AppProvider](https://shopify.dev/docs/api/shopify-app-remix/v3/entrypoints/appprovider.txt): Sets up the Polaris `AppProvider` and injects the App Bridge script.  This component extends the [`AppProvider`](https://polaris.shopify.com/components/utilities/app-provider) component from Polaris, and accepts all of its props except for `linkComponent`, which is overridden to use the Remix `Link` component.
- [AppProxyForm](https://shopify.dev/docs/api/shopify-app-remix/v3/app-proxy-components/appproxyform.txt): Sets up a Remix `<Form>` component that works when rendered on an app proxy page.  Supports any properties accepted by the `<Form>` component.  Because Remix doesn't support URL rewriting, any route using this component should <b>match the pathname of the proxy URL exactly</b>, and <b>end in a trailing slash</b> (e.g., `https://<shop>/apps/proxy/`), or set the Remix Form prop `navigate` to `false`.
- [AppProxyLink](https://shopify.dev/docs/api/shopify-app-remix/v3/app-proxy-components/appproxylink.txt): Sets up an `<a />` HTML element that works when rendered behind an app proxy.  Supports any properties accepted by the `<a />` HTML element.
- [AppProxyProvider](https://shopify.dev/docs/api/shopify-app-remix/v3/entrypoints/appproxyprovider.txt): Sets up a page to render behind a Shopify app proxy, enabling JavaScript and CSS to be loaded from the app.  Also provides components that enable using other components such as links and forms within proxies.  > Caution: Because Remix doesn't support URL rewriting, any route using this component should <b>match the pathname of the proxy URL exactly</b>, and <b>end in a trailing slash</b> (e.g., `https://<shop>/apps/proxy/`).
- [Admin](https://shopify.dev/docs/api/shopify-app-remix/v3/authenticate/admin.txt): Contains methods for authenticating and interacting with the Admin API.  This function can handle requests for apps embedded in the Admin, Admin extensions, or non-embedded apps.
- [Billing](https://shopify.dev/docs/api/shopify-app-remix/v3/apis/billing.txt): Contains function used to bill merchants for your app with the Billing API.  This object is returned on authenticated Admin requests.  > Note: [Managed App Pricing](https://shopify.dev/docs/apps/launch/billing/managed-pricing) is now available. Define your app’s pricing plans directly in the Shopify Partner Dashboard, without needing to use the Billing API.
- [Scopes](https://shopify.dev/docs/api/shopify-app-remix/v3/apis/scopes.txt): Contains functions used to manage scopes for your app.  This object is returned on authenticated Admin requests.
- [Flow](https://shopify.dev/docs/api/shopify-app-remix/v3/authenticate/flow.txt): Contains functions for verifying Shopify Flow extensions.  See the [Flow documentation](https://shopify.dev/docs/apps/flow/actions/endpoints) for more information.
- [Fulfillment Service](https://shopify.dev/docs/api/shopify-app-remix/v3/authenticate/fulfillment-service.txt): Contains functions for verifying fulfillment service requests.  See the [fulfillment service documentation](https://shopify.dev/docs/apps/fulfillment/fulfillment-service-apps) for more information.
- [App proxy](https://shopify.dev/docs/api/shopify-app-remix/v3/authenticate/public/app-proxy.txt): [App proxies](https://shopify.dev/docs/apps/online-store/app-proxies) take requests to Shopify links, and redirect them to external links. The `authenticate.public.appProxy` function validates requests made to app proxies, and returns a context to enable querying Shopify APIs.  > Note: If the store has not installed the app, store-related properties such as `admin` or `storefront` will be `undefined`
- [Checkout](https://shopify.dev/docs/api/shopify-app-remix/v3/authenticate/public/checkout.txt): The `authenticate.public.checkout` function ensures that checkout extension requests are coming from Shopify, and returns helpers to respond with the correct headers.
- [Customer account](https://shopify.dev/docs/api/shopify-app-remix/v3/authenticate/public/customer-account.txt): The `authenticate.public.customerAccount` function ensures that customer account extension requests are coming from Shopify, and returns helpers to respond with the correct headers.
- [Webhook](https://shopify.dev/docs/api/shopify-app-remix/v3/authenticate/webhook.txt): Contains functions for verifying Shopify webhooks.
- [Admin API](https://shopify.dev/docs/api/shopify-app-remix/v3/apis/admin-api.txt): Contains objects used to interact with the Admin API.  This object is returned as part of different contexts, such as [`admin`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/admin), [`unauthenticated.admin`](https://shopify.dev/docs/api/shopify-app-remix/unauthenticated/unauthenticated-admin), and [`webhook`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/webhook).
- [Storefront API](https://shopify.dev/docs/api/shopify-app-remix/v3/apis/storefront-api.txt): Contains objects used to interact with the Storefront API.  This object is returned as part of different contexts, such as [`appProxy`](https://shopify.dev/docs/api/shopify-app-remix/authenticate/public/app-proxy), and [`unauthenticated.storefront`](https://shopify.dev/docs/api/shopify-app-remix/unauthenticated/unauthenticated-storefront).
- [shopifyApp](https://shopify.dev/docs/api/shopify-app-remix/v3/entrypoints/shopifyapp.txt): Returns a set of functions that can be used by the app's backend to be able to respond to all Shopify requests.  The shape of the returned object changes depending on the value of `distribution`. If it is `AppDistribution.ShopifyAdmin`, then only `ShopifyAppBase` objects are returned, otherwise `ShopifyAppLogin` objects are included.
- [Unauthenticated admin](https://shopify.dev/docs/api/shopify-app-remix/v3/unauthenticated/unauthenticated-admin.txt): Allows interacting with the Admin API when working outside of Shopify requests. This enables apps to integrate with 3rd party services and perform background tasks.  > Caution: > This function doesn't perform **any** validation and shouldn't rely on raw user input.  When using this function, consider the following:  #### Background tasks  Apps should ensure that the shop domain is authenticated when enqueueing jobs.  #### 3rd party service requests  Apps must obtain the shop domain from the 3rd party service in a secure way.
- [Unauthenticated storefront](https://shopify.dev/docs/api/shopify-app-remix/v3/unauthenticated/unauthenticated-storefront.txt): Allows interacting with the Storefront API when working outside of Shopify requests. This enables apps to integrate with 3rd party services and perform background tasks.  > Caution: > This function doesn't perform **any** validation and shouldn't rely on raw user input.  When using this function, consider the following:  #### Background tasks  Apps should ensure that the shop domain is authenticated when enqueueing jobs.  #### 3rd party service requests  Apps must obtain the shop domain from the 3rd party service in a secure way.