@shopify/shopify-app-remix 4.2.0 → 5.0.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@shopify/shopify-app-remix",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "description": "Shopify Remix - to simplify the building of Shopify Apps with Remix",
   "engines": {
-    "node": ">=20.10.0"
+    "node": ">=22.0.0"
   },
   "repository": {
     "type": "git",
@@ -66,25 +66,25 @@
     "Storefront API"
   ],
   "devDependencies": {
-    "@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",
+    "@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.3",
     "@shopify/polaris": "^12.18.0",
     "@shopify/react-testing": "^6.0.0",
-    "@shopify/shopify-app-session-storage-memory": "^6.0.0",
-    "@types/react": "^19.2.9",
-    "jest-fetch-mock": "^3.0.3"
+    "@shopify/shopify-app-session-storage-memory": "^7.0.0",
+    "@types/react": "^19.2.17",
+    "jest-fetch-mock": "^3.2.0"
   },
   "dependencies": {
-    "@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",
+    "@remix-run/server-runtime": "^2.17.5",
+    "@shopify/admin-api-client": "^2.0.0",
+    "@shopify/shopify-api": "^14.0.0",
+    "@shopify/shopify-app-session-storage": "^6.0.0",
+    "@shopify/storefront-api-client": "^2.0.0",
     "compare-versions": "^6.1.1",
-    "isbot": "^5.1.34"
+    "isbot": "^5.2.0"
   },
   "peerDependencies": {
     "@remix-run/node": "*",
@@ -113,7 +113,6 @@
   "scripts": {
     "build-docs": "sh docs/build-docs.sh",
     "validate-docs": "sh ./docs/build-docs.sh isTest && pnpm compare-docs",
-    "lint": "eslint .",
     "build": "pnpm rollup && pnpm tsc -p ./tsconfig.build.json",
     "tsc": "tsc",
     "test": "jest",

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

@@ -12,6 +12,10 @@ 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'

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

@@ -1,4 +1,4 @@
-import {useContext} from 'react';
+import {forwardRef, useContext} from 'react';
 import {Form, type FormProps} from '@remix-run/react';
 
 import {AppProxyProviderContext} from '../AppProxyProvider';
@@ -62,21 +62,24 @@ export interface AppProxyFormProps extends FormProps {
  *   );
  * }
  * ```
+ * @publicDocs
  */
-export function AppProxyForm(props: AppProxyFormProps) {
-  const context = useContext(AppProxyProviderContext);
+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',
-    );
-  }
+    if (!context) {
+      throw new Error(
+        'AppProxyForm must be used within an AppProxyProvider component',
+      );
+    }
 
-  const {children, action, ...otherProps} = props;
+    const {children, action, ...otherProps} = props;
 
-  return (
-    <Form action={context.formatUrl(action, false)} {...otherProps}>
-      {children}
-    </Form>
-  );
-}
+    return (
+      <Form action={context.formatUrl(action, false)} {...otherProps} ref={ref}>
+        {children}
+      </Form>
+    );
+  },
+);

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

@@ -1,4 +1,4 @@
-import {useContext} from 'react';
+import {forwardRef, useContext} from 'react';
 
 import {AppProxyProviderContext} from '../AppProxyProvider';
 
@@ -38,21 +38,24 @@ export interface AppProxyLinkProps extends React.DetailedHTMLProps<
  *   );
  * }
  * ```
+ * @publicDocs
  */
-export function AppProxyLink(props: AppProxyLinkProps) {
-  const context = useContext(AppProxyProviderContext);
+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',
-    );
-  }
+    if (!context) {
+      throw new Error(
+        'AppProxyLink must be used within an AppProxyProvider component',
+      );
+    }
 
-  const {children, href, ...otherProps} = props;
+    const {children, href, ...otherProps} = props;
 
-  return (
-    <a href={context.formatUrl(href)} {...otherProps}>
-      {children}
-    </a>
-  );
-}
+    return (
+      <a href={context.formatUrl(href)} {...otherProps} ref={ref}>
+        {children}
+      </a>
+    );
+  },
+);

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

@@ -1,5 +1,9 @@
 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.

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

@@ -11,4 +11,4 @@ export {
   BASE64_HOST,
   USER_ID,
 } from '@shopify/shopify-api/test-helpers';
-export const GRAPHQL_URL = `https://${TEST_SHOP}/admin/api/${ApiVersion.July25}/graphql.json`;
+export const GRAPHQL_URL = `https://${TEST_SHOP}/admin/api/${ApiVersion.July26}/graphql.json`;

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

@@ -18,7 +18,7 @@ export function expectAdminApiClient(
       const {admin, actualSession} = await factory();
       await mockExternalRequest({
         request: new Request(
-          `https://${TEST_SHOP}/admin/api/${ApiVersion.July25}/graphql.json`,
+          `https://${TEST_SHOP}/admin/api/${ApiVersion.July26}/graphql.json`,
           {
             method: 'POST',
             headers: {'X-Shopify-Access-Token': actualSession.accessToken!},

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

@@ -18,7 +18,7 @@ export function expectStorefrontApiClient(
     const apiResponse = {data: {blogs: {nodes: [{id: 1}]}}, headers: {}};
     await mockExternalRequest({
       request: new Request(
-        `https://${TEST_SHOP}/api/${ApiVersion.July25}/graphql.json`,
+        `https://${TEST_SHOP}/api/${ApiVersion.July26}/graphql.json`,
         {
           method: 'POST',
           headers: {

package/src/server/__test-helpers/mock-graphql-request.ts

@@ -10,7 +10,7 @@ export interface MockGraphqlRequestArg {
 }
 
 export function mockGraphqlRequest(
-  apiVersion = ApiVersion.July25,
+  apiVersion = ApiVersion.July26,
   shopUrl = TEST_SHOP,
 ) {
   return async function ({
@@ -32,7 +32,7 @@ export function mockGraphqlRequest(
 }
 
 export function mockGraphqlRequests(
-  apiVersion = ApiVersion.July25,
+  apiVersion = ApiVersion.July26,
   shopUrl = TEST_SHOP,
 ) {
   return async function (...mocks: MockGraphqlRequestArg[]) {

package/src/server/__test-helpers/request-mock.ts

@@ -99,7 +99,7 @@ export async function validateMocks() {
       // TODO: we're currently not checking the headers properly. We should fix this.
       Object.entries(request.headers).forEach(([key, value]) => {
         expected.headers[key] = value;
-        actual.headers[key] = (init?.headers as any)[key];
+        actual.headers[key] = (init?.headers as any)?.[key];
       });
     }
 

package/src/server/__test-helpers/setup-non-embedded-flow.ts

@@ -14,7 +14,7 @@ export async function setUpNonEmbeddedFlow() {
   const session = await setUpValidSession(shopify.sessionStorage);
 
   const request = new Request(`${APP_URL}?shop=${TEST_SHOP}`);
-  signRequestCookie({
+  await signRequestCookie({
     request,
     cookieName: SESSION_COOKIE_NAME,
     cookieValue: session.id,

package/src/server/__test-helpers/setup-valid-request.ts

@@ -20,8 +20,7 @@ interface ValidExtensionRequestOptions {
 }
 
 type ValidRequestOptions =
-  | ValidBaseRequestOptions
-  | ValidExtensionRequestOptions;
+  ValidBaseRequestOptions | ValidExtensionRequestOptions;
 
 export async function setupValidRequest(
   shopify: ShopifyApp<any>,

package/src/server/__test-helpers/sign-request-cookie.ts

@@ -1,6 +1,12 @@
-import {getHmac} from './get-hmac';
+import {
+  Cookies,
+  NormalizedRequest,
+  NormalizedResponse,
+} from '@shopify/shopify-api/runtime';
 
-export function signRequestCookie({
+import {API_SECRET_KEY} from './const';
+
+export async function signRequestCookie({
   request,
   cookieName,
   cookieValue,
@@ -9,13 +15,18 @@ export function signRequestCookie({
   cookieName: string;
   cookieValue: string;
 }) {
-  const signedCookieValue = getHmac(cookieValue);
-
-  request.headers.set(
-    'Cookie',
-    [
-      `${cookieName}=${cookieValue}`,
-      `${cookieName}.sig=${signedCookieValue}`,
-    ].join(';'),
+  const cookies = new Cookies(
+    {headers: {}} as NormalizedRequest,
+    {} as NormalizedResponse,
+    {keys: [API_SECRET_KEY]},
   );
+
+  await cookies.setAndSign(cookieName, cookieValue);
+
+  const cookieHeader = cookies
+    .toHeaders()
+    .map((cookie) => cookie.split(';')[0])
+    .join(';');
+
+  request.headers.set('Cookie', cookieHeader);
 }

package/src/server/__test-helpers/test-config.ts

@@ -19,7 +19,7 @@ const TEST_FUTURE_FLAGS: Required<{[key in keyof FutureFlags]: true}> = {
 
 // Override the helper's future flags and logger settings for our purposes
 const TEST_CONFIG = {
-  apiVersion: ApiVersion.July25,
+  apiVersion: ApiVersion.July26,
   isEmbeddedApp: true,
   future: TEST_FUTURE_FLAGS,
   logger: {

package/src/server/authenticate/admin/authenticate.ts

@@ -80,8 +80,7 @@ export function authStrategyFactory<ConfigArg extends AppConfigArg>({
   }
 
   type AdminContextBase =
-    | EmbeddedAdminContext<ConfigArg>
-    | NonEmbeddedAdminContext<ConfigArg>;
+    EmbeddedAdminContext<ConfigArg> | NonEmbeddedAdminContext<ConfigArg>;
 
   function createContext(
     request: Request,
@@ -157,13 +156,11 @@ export function authStrategyFactory<ConfigArg extends AppConfigArg>({
         await ensureSessionTokenSearchParamIfRequired(params, request);
       }
 
-      logger.info('Authenticating admin request', {
-        shop: getShopFromRequest(request),
-      });
-
       const {payload, shop, sessionId, sessionToken} =
         await getSessionTokenContext(params, request);
 
+      logger.info('Authenticating admin request', {shop});
+
       logger.debug('Loading session from storage', {shop, sessionId});
       const existingSession = sessionId
         ? await config.sessionStorage!.loadSession(sessionId)

package/src/server/authenticate/admin/billing/types.ts

@@ -118,6 +118,10 @@ export interface UpdateUsageCappedAmountOptions {
   };
 }
 
+/**
+ * Provides utilities that apps can use to request billing for the app using the Admin API.
+ * @publicDocs
+ */
 export interface BillingContext<Config extends AppConfigArg> {
   /**
    * Checks if the shop has an active payment for any plan defined in the `billing` config option.

package/src/server/authenticate/admin/helpers/redirect.ts

@@ -48,8 +48,8 @@ export function redirectFactory(
 
     logger.debug('Redirecting', {shop, url: parsedUrl.toString()});
 
-    const isSameOrigin = parsedUrl.origin === config.appUrl;
-    if (isSameOrigin || url.startsWith('/')) {
+    const isSameOrigin = parsedUrl.origin === new URL(config.appUrl).origin;
+    if (isSameOrigin) {
       searchParams.forEach((value, key) => {
         if (!parsedUrl.searchParams.has(key)) {
           parsedUrl.searchParams.set(key, value);

package/src/server/authenticate/admin/helpers/validate-redirect-url.ts

@@ -33,7 +33,7 @@ function isSafe(
 
   try {
     url = new URL(redirectUrl, domain);
-  } catch (error) {
+  } catch (_error) {
     return false;
   }
 

package/src/server/authenticate/admin/scope/types.ts

@@ -1,5 +1,6 @@
 /**
- * The Scopes API enables embedded apps and extensions to request merchant consent for access scopes.
+ * Provides utilities that apps can use to [manage scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes) for the app using the Admin API.
+ * @publicDocs
  */
 export interface ScopesApiContext {
   /**

package/src/server/authenticate/admin/types.ts

@@ -148,6 +148,10 @@ export interface EmbeddedAdminContext<
    *
    * Returned only if `isEmbeddedApp` is `true`.
    *
+   * Request parameters (including `id_token`, `shop`, `host`, and `embedded`) are only copied to the destination when
+   * it resolves to the same origin as `appUrl`. This helper does not validate the destination URL — avoid passing
+   * unvalidated user input (for example, a raw `?next=` query parameter) and use an allow-list of paths instead.
+   *
    * @example
    * <caption>Redirecting to an app route.</caption>
    * <description>Use the `redirect` helper to safely redirect between pages.</description>
@@ -211,6 +215,12 @@ export interface ScopesContext {
 export type AdminContext<Config extends AppConfigArg> =
   EmbeddedTypedAdminContext<Config> & ScopesContext;
 
+/**
+ * Authenticates requests coming from the Shopify admin.
+ *
+ * The shape of the returned object changes depending on the `isEmbeddedApp` config.
+ * @publicDocs
+ */
 export type AuthenticateAdmin<Config extends AppConfigArg> = (
   request: Request,
 ) => Promise<AdminContext<Config>>;

package/src/server/authenticate/flow/types.ts

@@ -82,4 +82,8 @@ export interface FlowContext {
   admin: AdminApiContext;
 }
 
+/**
+ * Verifies requests coming from Shopify Flow extensions.
+ * @publicDocs
+ */
 export type AuthenticateFlow = (request: Request) => Promise<FlowContext>;

package/src/server/authenticate/fulfillment-service/types.ts

@@ -77,6 +77,10 @@ export interface FulfillmentServiceContext {
   payload: FulfillmentServicePayload;
 }
 
+/**
+ * Verifies requests coming from Shopify to fulfillment service apps.
+ * @publicDocs
+ */
 export type AuthenticateFulfillmentService = (
   request: Request,
 ) => Promise<FulfillmentServiceContext>;

package/src/server/authenticate/public/appProxy/authenticate.ts

@@ -95,10 +95,9 @@ async function validateAppProxyHmac(
       searchParams.delete('index');
     }
 
-    let isValid = await api.utils.validateHmac(
-      Object.fromEntries(searchParams.entries()),
-      {signator: 'appProxy'},
-    );
+    let isValid = await api.utils.validateHmac(searchParams, {
+      signator: 'appProxy',
+    });
 
     if (!isValid) {
       const cleanPath = url.pathname
@@ -111,20 +110,18 @@ async function validateAppProxyHmac(
         `?_data=${data}&${searchParams.toString().replace(/^\?/, '')}`,
       );
 
-      isValid = await api.utils.validateHmac(
-        Object.fromEntries(searchParams.entries()),
-        {signator: 'appProxy'},
-      );
+      isValid = await api.utils.validateHmac(searchParams, {
+        signator: 'appProxy',
+      });
 
       if (!isValid) {
         const searchParams = new URLSearchParams(
           `?_data=${data}._index&${url.search.replace(/^\?/, '')}`,
         );
 
-        isValid = await api.utils.validateHmac(
-          Object.fromEntries(searchParams.entries()),
-          {signator: 'appProxy'},
-        );
+        isValid = await api.utils.validateHmac(searchParams, {
+          signator: 'appProxy',
+        });
       }
     }
 

package/src/server/authenticate/public/appProxy/types.ts

@@ -2,6 +2,10 @@ import {Session} from '@shopify/shopify-api';
 
 import {AdminApiContext, StorefrontContext} from '../../../clients';
 
+/**
+ * Authenticates requests coming to the app from Shopify app proxies.
+ * @publicDocs
+ */
 export type AuthenticateAppProxy = (
   request: Request,
 ) => Promise<AppProxyContext | AppProxyContextWithSession>;

package/src/server/authenticate/public/checkout/types.ts

@@ -2,6 +2,10 @@ import {JwtPayload} from '@shopify/shopify-api';
 
 import {EnsureCORSFunction} from '../../helpers/ensure-cors-headers';
 
+/**
+ * Authenticates requests coming from Shopify checkout extensions.
+ * @publicDocs
+ */
 export type AuthenticateCheckout = (
   request: Request,
   options?: AuthenticateCheckoutOptions,

package/src/server/authenticate/public/customer-account/authenticate.public.customerAccount.doc.example.ts

@@ -10,7 +10,8 @@ export const loader = async ({request}: LoaderFunctionArgs) => {
 };
 
 export const action = async ({request}: ActionFunctionArgs) => {
-  const {cors, sessionToken} = await authenticate.public.customerAccount(request);
+  const {cors, sessionToken} =
+    await authenticate.public.customerAccount(request);
 
   // Get offers for the customer
   const offers = getOffers(sessionToken.des, sessionToken.sub);

package/src/server/authenticate/public/customer-account/types.ts

@@ -2,6 +2,10 @@ import {JwtPayload} from '@shopify/shopify-api';
 
 import {EnsureCORSFunction} from '../../helpers/ensure-cors-headers';
 
+/**
+ * Authenticates requests coming from Shopify customer account extensions.
+ * @publicDocs
+ */
 export type AuthenticateCustomerAccount = (
   request: Request,
   options?: AuthenticateCustomerAccountOptions,

package/src/server/authenticate/webhooks/authenticate.ts

@@ -60,7 +60,6 @@ export function authenticateWebhookFactory<Topics extends string>(
         topic: check.topic as Topics,
         webhookId: check.webhookId,
         payload: JSON.parse(rawBody),
-        subTopic: check.subTopic || undefined,
         session: undefined,
         admin: undefined,
         webhookType: check.webhookType,
@@ -73,7 +72,7 @@ export function authenticateWebhookFactory<Topics extends string>(
         apiVersion: check.apiVersion,
         shop: check.domain,
         topic: check.topic as Topics,
-        webhookId: check.eventId,
+        webhookId: check.webhookId,
         payload: JSON.parse(rawBody),
         session: undefined,
         admin: undefined,

package/src/server/authenticate/webhooks/authenticate.webhooks.doc.example.ts

@@ -30,13 +30,13 @@ export const action = async ({request}: ActionFunctionArgs) => {
           }
         }
       `,
-      {
-        variables: {
-          productId: payload.admin_graphql_api_id,
-          time: new Date().toISOString(),
+        {
+          variables: {
+            productId: payload.admin_graphql_api_id,
+            time: new Date().toISOString(),
+          },
         },
-      },
-    );
+      );
   }
 
   return new Response();

package/src/server/authenticate/webhooks/types.ts

@@ -75,11 +75,8 @@ interface Context<Topics = string | number | symbol> {
   topic: Topics;
 
   /**
-   * A unique ID for the webhook. Useful to keep track of which events your app has already processed.
-   *
-   * For events webhooks (`webhookType === 'events'`), this is set to the `eventId` value for
-   * backwards compatibility. Prefer using `eventId` directly for events webhooks — `webhookId`
-   * will be removed from events webhooks in the next major version.
+   * A unique ID for the webhook. This is the idempotency key — useful to keep track of which
+   * events your app has already processed.
    *
    * @example
    * <caption>Webhook ID.</caption>
@@ -121,26 +118,6 @@ interface Context<Topics = string | number | symbol> {
    */
   webhookType: WebhookTypeValue;
 
-  /**
-   * The sub-topic of the webhook. Only available for traditional webhooks.
-   *
-   * @example
-   * <caption>Webhook sub-topic.</caption>
-   * <description>Get the webhook sub-topic.</description>
-   * ```ts
-   * // /app/routes/webhooks.tsx
-   * import { ActionFunctionArgs } from "@remix-run/node";
-   * import { authenticate } from "../shopify.server";
-   *
-   * export const action = async ({ request }: ActionFunctionArgs) => {
-   *   const { subTopic } = await authenticate.webhook(request);
-   *   return new Response();
-   * };
-   * ```
-   *
-   */
-  subTopic?: string;
-
   /**
    * The name assigned to the webhook subscription. Only available for traditional webhooks.
    */
@@ -258,9 +235,12 @@ export interface WebhookContextWithSession<
 }
 
 export type WebhookContext<Topics = string | number | symbol> =
-  | WebhookContextWithoutSession<Topics>
-  | WebhookContextWithSession<Topics>;
+  WebhookContextWithoutSession<Topics> | WebhookContextWithSession<Topics>;
 
+/**
+ * Verifies requests coming from Shopify webhooks.
+ * @publicDocs
+ */
 export type AuthenticateWebhook<Topics = string | number | symbol> = (
   request: Request,
 ) => Promise<WebhookContext<Topics>>;

package/src/server/clients/admin/types.ts

@@ -16,6 +16,10 @@ export type HandleAdminClientError = (arg: {
   session: Session;
 }) => Promise<void>;
 
+/**
+ * Provides utilities that apps can use to make requests to the Admin API.
+ * @publicDocs
+ */
 export interface AdminApiContext {
   /**
    * Methods for interacting with the Shopify Admin GraphQL API

package/src/server/clients/storefront/types.ts

@@ -2,6 +2,10 @@ import {StorefrontOperations} from '@shopify/storefront-api-client';
 
 import {GraphQLClient} from '../types';
 
+/**
+ * Provides utilities that apps can use to make requests to the Storefront API.
+ * @publicDocs
+ */
 export interface StorefrontContext {
   /**
    * Method for interacting with the Shopify Storefront GraphQL API

package/src/server/config-types.ts

@@ -204,7 +204,7 @@ export interface AppConfigArg<
    *
    * const shopify = shopifyApp({
    *   // ...etc
-   *   apiVersion: ApiVersion.July25,
+   *   apiVersion: ApiVersion.July26,
    * });
    * ```
    */

package/src/server/future/flags.ts

@@ -4,6 +4,12 @@ import {AppConfig} from '../config-types';
 
 // When adding new flags, you should also add them to the `TEST_FUTURE_FLAGS` object in `test-config.ts` to ensure that
 // it doesn't cause regressions.
+/**
+ * Set future flags using the `future` configuration field to opt in to upcoming breaking changes.
+ *
+ * With this feature, you can prepare for major releases ahead of time, as well as try out new features before they are released.
+ * @publicDocs
+ */
 export interface FutureFlags {
   /**
    * When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange).