Skip to main content
Live with caveats. This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.

​
Goal

Choose the correct Shopify hosting mode and understand the ownership and credential boundaries before connecting a project.

​
Prerequisites

  • A GitHub-connected StackShift project
  • An active StackShift subscription
  • Shopify hosting enabled by the StackShift operator

​
Workflow

1
Connect a GitHub repository that StackShift detects as a supported Shopify app or storefront.
2
Select app hosting for an official Shopify React Router or Remix app, or storefront hosting for Hydrogen or a confirmed generic Node storefront.
3
Enter each target’s Shopify credentials on the project Shopify page and verify the target.
4
Deploy through the project workflow; use Shopify releases for apps and exact-build preview promotion for storefronts.

​
Responsibility boundary

  • StackShift hosts the app backend or headless storefront process, routing, builds, previews, managed app databases, and the StackShift-side release record.
  • Shopify remains the commerce system of record for stores, products, checkout, app configuration, extensions, app installations, and Shopify API authorization.
  • A Shopify app remains responsible for merchant OAuth, session-token validation, offline token lifecycle, and webhook HMAC verification in application code.
  • StackShift observes ingress metadata for app webhooks but never treats that observation as proof that the app validated the HMAC.

​
Who supplies which credentials

The person or team hosting the Shopify project supplies tenant credentials through that project’s Shopify page or authenticated project API. For a SaaS platform, that can be the app developer. For a self-hosted customer project, it can be the customer with access to the relevant Shopify app or store. Tenant credentials do not belong in the StackShift server environment. Platform operators configure only feature flags, the pinned Shopify CLI runner image, the runner network and proxy, the CLI version, and the Storefront API version.
  • App target: client ID, client secret, App Automation Token, committed Shopify TOML path/name, app URL, and scopes.
  • Storefront target: public or private Storefront API token; optionally storefront ID and Customer Account API client fields.
  • StackShift generates app session secrets and provisions separate development and production PostgreSQL databases.

​
Domains during testing

The required store_domain is the permanent example.myshopify.com store identity used for Shopify API calls. It is not a custom storefront domain and does not require buying a domain. Generated StackShift HTTPS URLs are sufficient for connection, credential verification, development, and previews. A custom domain is optional. Promotion accepts either an HTTPS StackShift-managed hostname or a project-owned custom domain whose DNS verification and SSL status are active.

​
Supported source shapes

  • App detection requires a shopify.app*.toml file and an official @shopify/shopify-app-react-router or @shopify/shopify-app-remix dependency.
  • Apps require Prisma or PostgreSQL session storage, a PostgreSQL provider, and a setup/migrate script containing prisma migrate deploy.
  • Storefront detection requires @shopify/hydrogen or @shopify/storefront-api-client.
  • Hydrogen must be deployable as a Node server with Express/React Router adapter signals and a start command. Oxygen-only projects are rejected.
  • A generic Node storefront requires explicit confirmation. Bun is rejected during connection. An app without a committed npm, pnpm, or Yarn lockfile cannot pass the frozen-install verification/release path.

​
Expected result

The project has one immutable Shopify connection whose kind is app or storefront, isolated target configuration, and launch checks based on verified runtime state.

​
Common failures

  • Shopify feature flag disabled
  • Repository does not match the supported app/storefront contract
  • The supplied store domain is not the canonical lowercase *.myshopify.com domain
  • A project already connected as one kind is being changed to the other kind

Configure Shopify app hosting

Prepare supported app source, separate Shopify app targets, committed TOML files, credentials, managed databases, and verification.

Configure Shopify storefront hosting

Connect Hydrogen or a confirmed Node storefront, obtain Storefront API credentials, isolate targets, and verify Shopify access.

Shopify security and troubleshooting

Credential storage and isolation guarantees, launch-check interpretation, stable failure codes, and a production diagnosis sequence.