@shopify/shopify-app-remix 4.1.1 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/shopify-app-remix",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "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",
+    "@babel/preset-env": "^7.28.6",
+    "@remix-run/node": "^2.17.4",
+    "@remix-run/react": "^2.17.4",
+    "@remix-run/testing": "^2.17.4",
     "@shopify/generate-docs": "^0.19.8",
     "@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.0",
+    "@types/react": "^19.2.9",
     "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.4",
+    "@shopify/admin-api-client": "^1.1.2",
+    "@shopify/shopify-api": "^13.0.0",
+    "@shopify/shopify-app-session-storage": "^5.0.0",
+    "@shopify/storefront-api-client": "^1.0.10",
     "compare-versions": "^6.1.1",
-    "isbot": "^5.1.32"
+    "isbot": "^5.1.34"
   },
   "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.doc.ts

@@ -0,0 +1,35 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'AppProvider',
+  descriptionType: 'AppProviderGeneratedType',
+  description: '',
+  category: 'Entrypoints',
+  type: 'component',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'AppProviderProps',
+      description: 'Props for the `AppProvider` component.',
+      type: 'AppProviderProps',
+      filePath: 'src/react/components/AppProvider/AppProvider.tsx',
+    },
+  ],
+  jsDocTypeExamples: ['AppProviderGeneratedType'],
+  related: [
+    {
+      name: 'App bridge',
+      subtitle: 'Learn more about App Bridge.',
+      url: '/docs/api/app-bridge-library',
+      type: 'shopify',
+    },
+    {
+      name: 'Polaris',
+      subtitle: 'Learn more about Polaris.',
+      url: '/docs/apps/tools/polaris',
+      type: 'shopify',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,147 @@
+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';
+
+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.doc.ts

@@ -0,0 +1,28 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'AppProxyForm',
+  descriptionType: 'AppProxyFormGeneratedType',
+  description: '',
+  category: 'App proxy components',
+  type: 'component',
+  isVisualComponent: false,
+  definitions: [],
+  jsDocTypeExamples: ['AppProxyFormGeneratedType'],
+  related: [
+    {
+      name: 'authenticate.public.appProxy',
+      subtitle: 'Authenticating app proxy requests.',
+      url: '/docs/api/shopify-app-remix/authenticate/public/app-proxy',
+      type: 'remix',
+    },
+    {
+      name: 'AppProxyProvider',
+      subtitle: 'Enable JavaScript in pages loaded through app proxies.',
+      url: '/docs/api/shopify-app-remix/app-proxy-components/appproxyprovider',
+      type: 'remix',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,82 @@
+import {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>
+ *   );
+ * }
+ * ```
+ */
+export function AppProxyForm(props: AppProxyFormProps) {
+  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}>
+      {children}
+    </Form>
+  );
+}

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

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

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

@@ -0,0 +1,28 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'AppProxyLink',
+  descriptionType: 'AppProxyLinkGeneratedType',
+  description: '',
+  category: 'App proxy components',
+  type: 'component',
+  isVisualComponent: false,
+  definitions: [],
+  jsDocTypeExamples: ['AppProxyLinkGeneratedType'],
+  related: [
+    {
+      name: 'authenticate.public.appProxy',
+      subtitle: 'Authenticating app proxy requests.',
+      url: '/docs/api/shopify-app-remix/authenticate/public/app-proxy',
+      type: 'remix',
+    },
+    {
+      name: 'AppProxyProvider',
+      subtitle: 'Enable JavaScript in pages loaded through app proxies.',
+      url: '/docs/api/shopify-app-remix/app-proxy-components/appproxyprovider',
+      type: 'remix',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,58 @@
+import {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>
+ *   );
+ * }
+ * ```
+ */
+export function AppProxyLink(props: AppProxyLinkProps) {
+  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}>
+      {children}
+    </a>
+  );
+}

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

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

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

@@ -0,0 +1,40 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'AppProxyProvider',
+  descriptionType: 'AppProxyProviderGeneratedType',
+  description: '',
+  category: 'Entrypoints',
+  type: 'component',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'AppProxyProviderProps',
+      description: 'Props for the `AppProxyProvider` component.',
+      type: 'AppProxyProviderProps',
+    },
+  ],
+  jsDocTypeExamples: ['AppProxyProviderGeneratedType'],
+  related: [
+    {
+      name: 'authenticate.public.appProxy',
+      subtitle: 'Authenticate app proxy requests.',
+      url: '/docs/api/shopify-app-remix/authenticate/public/app-proxy',
+      type: 'remix',
+    },
+    {
+      name: 'AppProxyForm',
+      subtitle: 'Render form elements in proxies.',
+      url: '/docs/api/shopify-app-remix/app-proxy-components/appproxyform',
+      type: 'remix',
+    },
+    {
+      name: 'AppProxyLink',
+      subtitle: 'Render link elements in proxies.',
+      url: '/docs/api/shopify-app-remix/app-proxy-components/appproxylink',
+      type: 'remix',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,100 @@
+import {createContext, useEffect, useState} from 'react';
+
+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`;