Implement domain transformations support for split-domain architectures

[weslleyaraujo]

Problem

Currently, multiple Shopify apps patch @shopify/shopify-api to enable local core development with split domain architecture. This creates maintenance burden and requires coordination across teams when the library changes.

Slack discussion

Affected apps:

• Bundles
• Subscriptions
• Combined Listings App

This PR introduces a proposal to solve this problem by adding a new domainTransformations configuration option that allows apps to define domain mappings without patching the library.

interface DomainTransformation {
  // Pattern to match source domain
  match: RegExp | string;

  // Transformation: function or template string
  transform: ((matches: RegExpMatchArray) => string | null) | string;

  // Whether to include in host validation (default: true)
  includeHost?: boolean;
}

Template-based transformation (simple):

import { shopifyApi } from "@shopify/shopify-api";

const shopify = shopifyApi({
  // ... other config ...
  domainTransformations: [
    {
      match: /^([a-zA-Z0-9][a-zA-Z0-9-_]*)\.my\.shop\.dev$/,
      transform: "$1.dev-api.shop.dev",
    },
  ],
});

Function-based transformation:

const shopify = shopifyApi({
  // ... other config ...
  domainTransformations: [
    {
      match: /^([a-zA-Z0-9-_]+)\.admin\.example\.com$/,
      transform: (matches) => {
        const shopName = matches[1];
        return shopName.startsWith("test-")
          ? `${shopName}.api-staging.example.com`
          : `${shopName}.api.example.com`;
      },
    },
  ],
});

For the affected apps, it would look like this:

// app/shopify.server.ts
import { shopifyApp } from "@shopify/shopify-app-remix/server";

const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  domainTransformations: isDevelopment
    ? [
        {
          match: /^([a-zA-Z0-9][a-zA-Z0-9-_]*)\.my\.shop\.dev$/,
          transform: "$1.dev-api.shop.dev",
        },
      ]
    : undefined,
});

Demo

Here is an example of the bundles app running locally with a custom build version of this PR:

PS: shopify-app-remix is also linked here, but is unrelated. Bundles has an outdated version, which is not compatible with the current shopify-app library.

Resources

• https://github.com/shop/issues-bundles-and-combined-listings/issues/1250