@shopify/shopify-app-remix 4.1.1 → 4.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/shopify-app-remix",
-  "version": "4.1.1",
+  "version": "4.2.1",
   "description": "Shopify Remix - to simplify the building of Shopify Apps with Remix",
   "engines": {
     "node": ">=20.10.0"
@@ -66,25 +66,25 @@
     "Storefront API"
   ],
   "devDependencies": {
-    "@babel/preset-env": "^7.28.5",
-    "@remix-run/node": "^2.17.2",
-    "@remix-run/react": "^2.17.3",
-    "@remix-run/testing": "^2.17.2",
-    "@shopify/generate-docs": "^0.19.8",
+    "@babel/preset-env": "^7.29.7",
+    "@remix-run/node": "^2.17.5",
+    "@remix-run/react": "^2.17.5",
+    "@remix-run/testing": "^2.17.5",
+    "@shopify/generate-docs": "^1.2.0",
     "@shopify/polaris": "^12.18.0",
     "@shopify/react-testing": "^6.0.0",
-    "@shopify/shopify-app-session-storage-memory": "^5.0.5",
-    "@types/react": "^19.2.2",
+    "@shopify/shopify-app-session-storage-memory": "^6.0.1",
+    "@types/react": "^19.2.16",
     "jest-fetch-mock": "^3.0.3"
   },
   "dependencies": {
-    "@remix-run/server-runtime": "^2.17.3",
-    "@shopify/admin-api-client": "^1.1.1",
-    "@shopify/shopify-api": "^12.3.0",
-    "@shopify/shopify-app-session-storage": "^4.0.5",
-    "@shopify/storefront-api-client": "^1.0.9",
+    "@remix-run/server-runtime": "^2.17.5",
+    "@shopify/admin-api-client": "^1.1.2",
+    "@shopify/shopify-api": "^13.1.0",
+    "@shopify/shopify-app-session-storage": "^5.0.1",
+    "@shopify/storefront-api-client": "^1.0.10",
     "compare-versions": "^6.1.1",
-    "isbot": "^5.1.32"
+    "isbot": "^5.1.40"
   },
   "peerDependencies": {
     "@remix-run/node": "*",
@@ -102,6 +102,10 @@
   },
   "files": [
     "dist/*",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
     "!build/**/__tests__",
     "!tsconfig.tsbuildinfo",
     "!node_modules"
@@ -109,7 +113,7 @@
   "scripts": {
     "build-docs": "sh docs/build-docs.sh",
     "validate-docs": "sh ./docs/build-docs.sh isTest && pnpm compare-docs",
-    "lint": "eslint . --ext .js,.ts",
+    "lint": "eslint .",
     "build": "pnpm rollup && pnpm tsc -p ./tsconfig.build.json",
     "tsc": "tsc",
     "test": "jest",

package/src/react/components/AppProvider/AppProvider.tsx

@@ -0,0 +1,151 @@
+import {
+  AppProvider as PolarisAppProvider,
+  AppProviderProps as PolarisAppProviderProps,
+} from '@shopify/polaris';
+// This leads to some TS errors, but it does compile to something that works
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import englishI18n from '@shopify/polaris/locales/en.json' with {type: 'json'};
+import {useNavigate} from '@remix-run/react';
+import {useEffect} from 'react';
+
+import {APP_BRIDGE_URL} from '../../const';
+import {RemixPolarisLink} from '../RemixPolarisLink';
+
+/**
+ * Props for the `AppProvider` component.
+ * @publicDocs
+ */
+export interface AppProviderProps extends Omit<
+  PolarisAppProviderProps,
+  'linkComponent' | 'i18n'
+> {
+  /**
+   * The API key for your Shopify app. This is the `Client ID` from the Partner Dashboard.
+   *
+   * When using the Shopify CLI, this is the `SHOPIFY_API_KEY` environment variable. If you're using the environment
+   * variable, then you need to pass it from the loader to the component.
+   */
+  apiKey: string;
+  /**
+   * Whether the app is loaded inside the Shopify Admin. Default is `true`.
+   *
+   * {@link https://shopify.dev/docs/apps/admin/embedded-app-home}
+   */
+  isEmbeddedApp?: boolean;
+  /**
+   * The internationalization (i18n) configuration for your Polaris provider.
+   *
+   * {@link https://polaris.shopify.com/components/utilities/app-provider}
+   */
+  i18n?: PolarisAppProviderProps['i18n'];
+  /**
+   * Used internally by Shopify. You don't need to set this.
+   * @private
+   */
+  __APP_BRIDGE_URL?: string;
+}
+
+/**
+ * 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.
+ *
+ * {@link https://polaris.shopify.com/components/utilities/app-provider}
+ * {@link https://shopify.dev/tools/app-bridge}
+ *
+ * @example
+ * <caption>Set up AppProvider.</caption>
+ * <description>Wrap your app in the `AppProvider` component and pass in your API key.</description>
+ * ```ts
+ * // /app/routes/**\/*.ts
+ * import {authenticate} from '~/shopify.server';
+ * import {AppProvider} from '@shopify/shopify-app-remix/react';
+ *
+ * export async function loader({ request }) {
+ *   await authenticate.admin(request);
+ *
+ *   return json({ apiKey: process.env.SHOPIFY_API_KEY });
+ * }
+ *
+ * export default function App() {
+ *   const { apiKey } = useLoaderData();
+ *
+ *   return (
+ *     <AppProvider isEmbeddedApp apiKey={apiKey}>
+ *       <Outlet />
+ *     </AppProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * <caption>Localize Polaris components.</caption>
+ * <description>Pass in a different locale for Polaris to translate its components.</description>
+ * ```ts
+ * // /app/routes/**\/*.ts
+ * import {authenticate} from '~/shopify.server';
+ * import {AppProvider} from '@shopify/shopify-app-remix/react';
+ *
+ * export async function loader({ request }) {
+ *   await authenticate.admin(request);
+ *
+ *   return json({
+ *     apiKey: process.env.SHOPIFY_API_KEY,
+ *     polarisTranslations: require("@shopify/polaris/locales/fr.json"),
+ *   });
+ * }
+ *
+ * export default function App() {
+ *   const { apiKey, polarisTranslations } = useLoaderData();
+ *
+ *   return (
+ *     <AppProvider apiKey={apiKey} i18n={polarisTranslations}>
+ *       <Outlet />
+ *     </AppProvider>
+ *   );
+ * }
+ * ```
+ */
+export function AppProvider(props: AppProviderProps) {
+  const {
+    children,
+    apiKey,
+    i18n,
+    isEmbeddedApp = true,
+    __APP_BRIDGE_URL = APP_BRIDGE_URL,
+    ...polarisProps
+  } = props;
+
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    const handleNavigate = (event: Event) => {
+      const href = (event.target as HTMLElement)?.getAttribute('href');
+      if (href) {
+        navigate(href);
+      }
+    };
+
+    addEventListener('shopify:navigate', handleNavigate);
+
+    return () => {
+      removeEventListener('shopify:navigate', handleNavigate);
+    };
+  }, [navigate]);
+
+  return (
+    <>
+      {isEmbeddedApp && <script src={__APP_BRIDGE_URL} data-api-key={apiKey} />}
+      <PolarisAppProvider
+        {...polarisProps}
+        linkComponent={RemixPolarisLink}
+        i18n={i18n || englishI18n}
+      >
+        {children}
+      </PolarisAppProvider>
+    </>
+  );
+}

package/src/react/components/AppProvider/index.ts

@@ -0,0 +1 @@
+export * from './AppProvider';

package/src/react/components/AppProxyForm/AppProxyForm.tsx

@@ -0,0 +1,85 @@
+import {forwardRef, useContext} from 'react';
+import {Form, type FormProps} from '@remix-run/react';
+
+import {AppProxyProviderContext} from '../AppProxyProvider';
+
+export interface AppProxyFormProps extends FormProps {
+  action: string;
+}
+
+/**
+ * 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`.
+ *
+ * @example
+ * <caption>Render a form element in a proxied route.</caption>
+ * <description>Use an `AppProxyForm` within an `AppProxy` to create a form.</description>
+ * ```ts
+ * // /app/routes/apps/appProxy.ts
+ * import {
+ *   AppProxyProvider,
+ *   AppProxyForm,
+ * } from "@shopify/shopify-app-remix/react";
+ * import { authenticate } from "~/shopify.server";
+ *
+ * export async function loader({ request }) {
+ *   await authenticate.public.appProxy(request);
+ *
+ *   return json({ appUrl: process.env.SHOPIFY_APP_URL });
+ * }
+ *
+ * export async function action({ request }) {
+ *   await authenticate.public.appProxy(request);
+ *
+ *   const formData = await request.formData();
+ *   const field = formData.get("field")?.toString();
+ *
+ *   // Perform actions
+ *   if (field) {
+ *     console.log("Field:", field);
+ *   }
+ *
+ *   // Return JSON to the client
+ *   return json({ message: "Success!" });
+ * }
+ *
+ * export default function App() {
+ *   const { appUrl } = useLoaderData();
+ *
+ *   return (
+ *     <AppProxyProvider appUrl={appUrl}>
+ *       <AppProxyForm action="/apps/appProxy" method="post">
+ *         <input type="text" name="field" />
+ *
+ *         <input type="submit" name="Submit" />
+ *       </AppProxyForm>
+ *     </AppProxyProvider>
+ *   );
+ * }
+ * ```
+ * @publicDocs
+ */
+export const AppProxyForm = forwardRef<HTMLFormElement, AppProxyFormProps>(
+  function AppProxyForm(props, ref) {
+    const context = useContext(AppProxyProviderContext);
+
+    if (!context) {
+      throw new Error(
+        'AppProxyForm must be used within an AppProxyProvider component',
+      );
+    }
+
+    const {children, action, ...otherProps} = props;
+
+    return (
+      <Form action={context.formatUrl(action, false)} {...otherProps} ref={ref}>
+        {children}
+      </Form>
+    );
+  },
+);

package/src/react/components/AppProxyForm/index.ts

@@ -0,0 +1 @@
+export {AppProxyForm, type AppProxyFormProps} from './AppProxyForm';

package/src/react/components/AppProxyLink/AppProxyLink.tsx

@@ -0,0 +1,61 @@
+import {forwardRef, useContext} from 'react';
+
+import {AppProxyProviderContext} from '../AppProxyProvider';
+
+export interface AppProxyLinkProps extends React.DetailedHTMLProps<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>,
+  HTMLAnchorElement
+> {
+  href: string;
+}
+
+/**
+ * Sets up an `<a />` HTML element that works when rendered behind an app proxy.
+ *
+ * Supports any properties accepted by the `<a />` HTML element.
+ *
+ * @example
+ * <caption>Link to a different route.</caption>
+ * <description>Use an `AppProxyLink` within an `AppProxyProvider` to link to a different proxied route.</description>
+ * ```ts
+ * // /app/routes/**\/*.ts
+ * import {authenticate} from '~/shopify.server';
+ * import {AppProxyProvider, AppProxyLink} from '@shopify/shopify-app-remix/react';
+ *
+ * export async function loader({ request }) {
+ *   await authenticate.public.appProxy(request);
+ *
+ *   return json({ appUrl: process.env.SHOPIFY_APP_URL });
+ * }
+ *
+ * export default function App() {
+ *   const { appUrl } = useLoaderData();
+ *
+ *   return (
+ *     <AppProxyProvider appUrl={appUrl}>
+ *       <AppProxyLink href="/other-proxy-route">Link to another route</AppProxyLink>
+ *     </AppProxyProvider>
+ *   );
+ * }
+ * ```
+ * @publicDocs
+ */
+export const AppProxyLink = forwardRef<HTMLAnchorElement, AppProxyLinkProps>(
+  function AppProxyLink(props, ref) {
+    const context = useContext(AppProxyProviderContext);
+
+    if (!context) {
+      throw new Error(
+        'AppProxyLink must be used within an AppProxyProvider component',
+      );
+    }
+
+    const {children, href, ...otherProps} = props;
+
+    return (
+      <a href={context.formatUrl(href)} {...otherProps} ref={ref}>
+        {children}
+      </a>
+    );
+  },
+);

package/src/react/components/AppProxyLink/index.ts

@@ -0,0 +1 @@
+export {AppProxyLink, type AppProxyLinkProps} from './AppProxyLink';

package/src/react/components/AppProxyProvider/AppProxyProvider.tsx

@@ -0,0 +1,104 @@
+import {createContext, useEffect, useState} from 'react';
+
+/**
+ * Props for the `AppProxyProvider` component.
+ * @publicDocs
+ */
+export interface AppProxyProviderProps {
+  /**
+   * The URL where the app is hosted. You can set this from the `SHOPIFY_APP_URL` environment variable.
+   */
+  appUrl: string;
+
+  /**
+   * The children to render.
+   */
+  children?: React.ReactNode;
+}
+
+type FormatUrlFunction = (
+  url: string | undefined,
+  addOrigin?: boolean,
+) => string | undefined;
+
+interface AppProxyProviderContextProps {
+  appUrl: string;
+  formatUrl: FormatUrlFunction;
+  requestUrl?: URL;
+}
+
+export const AppProxyProviderContext =
+  createContext<AppProxyProviderContextProps | null>(null);
+
+/**
+ * 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/`).
+ *
+ * @example
+ * <caption>Wrap a route with an AppProxyProvider component.</caption>
+ * <description>Wrap your route component in the `AppProxyProvider` component and pass in your app URL.</description>
+ * ```ts
+ * // /app/routes/**\/*.ts
+ * import {authenticate} from '~/shopify.server';
+ * import {AppProxyProvider} from '@shopify/shopify-app-remix/react';
+ *
+ * export async function loader({ request }) {
+ *   await authenticate.public.appProxy(request);
+ *
+ *   return json({ appUrl: process.env.SHOPIFY_APP_URL });
+ * }
+ *
+ * export default function App() {
+ *   const { appUrl } = useLoaderData();
+ *
+ *   return (
+ *     <AppProxyProvider appUrl={appUrl}>
+ *       Page content
+ *     </AppProxyProvider>
+ *   );
+ * }
+ * ```
+ */
+export function AppProxyProvider(props: AppProxyProviderProps) {
+  const {children, appUrl} = props;
+  const [requestUrl, setRequestUrl] = useState<URL | undefined>();
+
+  useEffect(
+    () => setRequestUrl(new URL(window.location.href)),
+    [setRequestUrl],
+  );
+
+  return (
+    <AppProxyProviderContext.Provider
+      value={{appUrl, requestUrl, formatUrl: formatProxyUrl(requestUrl)}}
+    >
+      <base href={appUrl} />
+
+      {children}
+    </AppProxyProviderContext.Provider>
+  );
+}
+
+function formatProxyUrl(requestUrl: URL | undefined): FormatUrlFunction {
+  return (url: string | undefined, addOrigin = true) => {
+    if (!url) {
+      return url;
+    }
+
+    let finalUrl = url;
+
+    if (addOrigin && requestUrl && finalUrl.startsWith('/')) {
+      finalUrl = new URL(`${requestUrl.origin}${url}`).href;
+    }
+    if (!finalUrl.endsWith('/')) {
+      finalUrl = `${finalUrl}/`;
+    }
+
+    return finalUrl;
+  };
+}

package/src/react/components/AppProxyProvider/index.ts

@@ -0,0 +1,5 @@
+export {
+  AppProxyProvider,
+  type AppProxyProviderProps,
+  AppProxyProviderContext,
+} from './AppProxyProvider';

package/src/react/components/RemixPolarisLink.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import {Link} from '@remix-run/react';
+// Polaris' LinkProps doesn't match this type, so we need to import it directly
+import type {
+  LinkLikeComponent,
+  LinkLikeComponentProps,
+} from '@shopify/polaris/build/ts/src/utilities/link';
+
+export const RemixPolarisLink = React.forwardRef<
+  HTMLAnchorElement,
+  LinkLikeComponentProps
+>((props, ref) => (
+  <Link {...props} to={props.url ?? props.to} ref={ref} />
+)) as LinkLikeComponent;

package/src/react/components/index.ts

@@ -0,0 +1,4 @@
+export * from './AppProvider';
+export * from './AppProxyProvider';
+export * from './AppProxyForm';
+export * from './AppProxyLink';

package/src/react/const.ts

@@ -0,0 +1,2 @@
+export const APP_BRIDGE_URL =
+  'https://cdn.shopify.com/shopifycloud/app-bridge.js';

package/src/react/index.ts

@@ -0,0 +1 @@
+export * from './components';

package/src/server/__test-helpers/const.ts

@@ -0,0 +1,14 @@
+import {ApiVersion} from '@shopify/shopify-api';
+import {TEST_SHOP} from '@shopify/shopify-api/test-helpers';
+
+export {
+  API_KEY,
+  API_SECRET_KEY,
+  APP_URL,
+  TEST_SHOP_NAME,
+  TEST_SHOP,
+  SHOPIFY_HOST,
+  BASE64_HOST,
+  USER_ID,
+} from '@shopify/shopify-api/test-helpers';
+export const GRAPHQL_URL = `https://${TEST_SHOP}/admin/api/${ApiVersion.July25}/graphql.json`;

package/src/server/__test-helpers/expect-admin-api-client.ts

@@ -0,0 +1,51 @@
+import {ApiVersion, Session} from '@shopify/shopify-api';
+
+import type {AdminApiContext} from '../clients';
+
+import {TEST_SHOP} from './const';
+import {mockExternalRequest} from './request-mock';
+
+export function expectAdminApiClient(
+  factory: () => Promise<{
+    admin: AdminApiContext;
+    expectedSession: Session;
+    actualSession: Session;
+  }>,
+) {
+  describe('Graphql client', () => {
+    it('can perform requests', async () => {
+      // GIVEN
+      const {admin, actualSession} = await factory();
+      await mockExternalRequest({
+        request: new Request(
+          `https://${TEST_SHOP}/admin/api/${ApiVersion.July25}/graphql.json`,
+          {
+            method: 'POST',
+            headers: {'X-Shopify-Access-Token': actualSession.accessToken!},
+          },
+        ),
+        response: new Response(
+          JSON.stringify({data: {shop: {name: 'Test shop'}}}),
+        ),
+      });
+
+      // WHEN
+      const response = await admin.graphql('{ shop { name } }');
+
+      // THEN
+      expect(response.status).toEqual(200);
+      expect(await response.json()).toEqual({
+        data: {shop: {name: 'Test shop'}},
+        headers: {'Content-Type': ['application/json']},
+      });
+    });
+
+    it('returns a session object as part of the context', async () => {
+      // GIVEN
+      const {expectedSession, actualSession} = await factory();
+
+      // THEN
+      expect(expectedSession).toEqual(actualSession);
+    });
+  });
+}

package/src/server/__test-helpers/expect-begin-auth-redirect.ts

@@ -0,0 +1,22 @@
+import {TEST_SHOP} from './const';
+import {testConfig} from './test-config';
+
+export function expectBeginAuthRedirect(
+  config: ReturnType<typeof testConfig>,
+  response: Response,
+) {
+  expect(response.status).toEqual(302);
+
+  const {hostname, pathname, searchParams} = new URL(
+    response.headers.get('location')!,
+  );
+
+  expect(hostname).toBe(TEST_SHOP);
+  expect(pathname).toBe('/admin/oauth/authorize');
+  expect(searchParams.get('client_id')).toBe(config.apiKey);
+  expect(searchParams.get('scope')).toBe(config.scopes!.toString());
+  expect(searchParams.get('redirect_uri')).toBe(
+    `${config.appUrl}/auth/callback`,
+  );
+  expect(searchParams.get('state')).toStrictEqual(expect.any(String));
+}

package/src/server/__test-helpers/expect-document-request-headers.ts

@@ -0,0 +1,25 @@
+import {APP_BRIDGE_URL} from '../authenticate/const';
+
+import {TEST_SHOP} from './const';
+
+export function expectDocumentRequestHeaders(
+  response: Response,
+  isEmbeddedApp = true,
+) {
+  const headers = response.headers;
+
+  if (isEmbeddedApp) {
+    expect(headers.get('Content-Security-Policy')).toEqual(
+      `frame-ancestors https://${encodeURIComponent(
+        TEST_SHOP,
+      )} https://admin.shopify.com https://*.spin.dev https://admin.myshopify.io https://admin.shop.dev;`,
+    );
+    expect(headers.get('Link')).toEqual(
+      `<${APP_BRIDGE_URL}>; rel="preload"; as="script";`,
+    );
+  } else {
+    expect(headers.get('Content-Security-Policy')).toEqual(
+      `frame-ancestors 'none';`,
+    );
+  }
+}

package/src/server/__test-helpers/expect-exit-iframe.ts

@@ -0,0 +1,37 @@
+import {APP_URL, BASE64_HOST, TEST_SHOP} from './const';
+
+interface ExpectExitIframeRedirectOptions {
+  shop?: string;
+  host?: string | null;
+  destination?: string;
+  addHostToExitIframePath?: boolean;
+}
+
+export function expectExitIframeRedirect(
+  response: Response,
+  {
+    shop = TEST_SHOP,
+    host = BASE64_HOST,
+    destination = `/auth?shop=${shop}`,
+    addHostToExitIframePath = true,
+  }: ExpectExitIframeRedirectOptions = {},
+) {
+  expect(response.status).toBe(302);
+
+  const {pathname, searchParams} = new URL(
+    response.headers.get('location')!,
+    APP_URL,
+  );
+  expect(pathname).toBe('/auth/exit-iframe');
+
+  expect(searchParams.get('shop')).toBe(shop);
+
+  let expectedDestination = destination;
+  if (host) {
+    expect(searchParams.get('host')).toBe(host);
+    if (addHostToExitIframePath) {
+      expectedDestination = destination.concat(`&host=${host}`);
+    }
+  }
+  expect(searchParams.get('exitIframe')).toBe(expectedDestination);
+}

package/src/server/__test-helpers/expect-login-redirect.ts

@@ -0,0 +1,8 @@
+import {APP_URL} from './const';
+
+export function expectLoginRedirect(response: Response) {
+  expect(response.status).toBe(302);
+
+  const {pathname} = new URL(response.headers.get('location')!, APP_URL);
+  expect(pathname).toBe('/auth/login');
+}