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

Connect and verify isolated development and production targets for a supported Shopify app backend.

​
Prerequisites

  • A supported official Shopify app repository connected through GitHub
  • Distinct primary and development branches
  • Two different Shopify apps or client IDs, one for each environment

​
Workflow

1
Commit separate development and production Shopify TOML configuration files and current webhook API versions.
2
Connect the project as kind app, provide the canonical store domain, and select a development branch different from the project primary branch.
3
Wait for the durable connect operation to create both project environments and managed PostgreSQL databases.
4
Enter the development target values, save, and run verification; repeat with different production values.
5
Resolve every launch check before treating the application as production-ready.

​
Repository contract

  • The app uses the official Shopify React Router or Remix package.
  • The package manifest identifies Prisma or PostgreSQL-backed session storage, and Prisma declares PostgreSQL as its provider.
  • One of setup, db:setup, migrate, or deploy contains prisma migrate deploy; StackShift records that exact script as the release command.
  • Source contains authenticate.admin and an APP_UNINSTALLED or app/uninstalled webhook handler signal.
  • The official-template detection must indicate expiring offline access-token support; explicitly disabling it is rejected.
  • Each target’s committed TOML client_id matches the client ID entered in StackShift and declares a webhook api_version in Shopify’s current four-version support window. Shopify documents the quarterly lifecycle in API versioning.

​
Create target credentials

Create and manage apps in the Shopify Dev Dashboard. Use separate app records for development and production so their client IDs, URLs, installations, and release histories cannot collide. Copy the client ID and client secret from each app’s Settings. Create an app-scoped App Automation Token in the same app. Shopify shows a new automation token once; store it immediately and rotate it before its selected expiry.
  • config_path: repository-relative TOML path; absolute paths and parent traversal are rejected.
  • config_name: optional Shopify CLI config name. When both fields exist, it must match the name derived from the TOML filename.
  • app_url: HTTPS origin only, with no credentials, query, fragment, or non-443 port.
  • scopes: the comma-separated scopes expected by the app configuration.
  • Leaving an already stored secret field blank keeps the current value; responses return only has_* booleans.

​
Resources and runtime variables

  • Connection creates stable production and development project environments, with primary-branch and development-branch auto-deploy behavior respectively.
  • It provisions separate PostgreSQL 16 databases named shopify-production and shopify-development, each initially configured with 1 GB storage.
  • At runtime StackShift injects PUBLIC_STORE_DOMAIN, SHOPIFY_APP_URL, SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SCOPES, SESSION_SECRET, and DATABASE_URL.
  • The primary branch maps only to production. The configured development branch maps only to development. Other app branches are rejected by Shopify runtime isolation.

​
What verification proves

  • All required credentials and a generated session secret are present.
  • The committed config at the correct branch exists, parses, matches the target client ID, and uses a supported webhook API version.
  • The App Automation Token can list versions for that exact client ID through the pinned Shopify CLI.
  • The bound database is running, project-owned PostgreSQL and has an available connection string.
  • The HTTPS app URL passes TLS/hostname validation and the callback and uninstall-webhook routes are reachable. A 2xx–4xx response other than 404 counts as route presence.
  • Across targets, client IDs, application URLs, and database IDs are all different.

​
Expected result

Development and production are independently verified with distinct app identities, HTTPS URLs, generated session secrets, and running project-owned PostgreSQL databases.

​
Common failures

  • Development branch equals the primary branch
  • Development and production reuse a client ID, URL, or database
  • TOML client ID or config name does not match the saved target
  • Automation token belongs to another Shopify app or has expired
  • Callback or webhook route returns 404
  • Webhook API version is missing or outside the latest four stable quarterly versions

Shopify hosting overview

What StackShift hosts, what remains in Shopify, who supplies credentials, and how app and storefront hosting differ.

Shopify app releases and rollbacks

How backend deployments are coupled to deterministic Shopify configuration and extension releases, retries, and compensation.

Shopify security and troubleshooting

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