> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Shopify app hosting

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

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## 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

<Steps>
  <Step>
    Commit separate development and production Shopify TOML configuration files and current webhook API versions.
  </Step>

  <Step>
    Connect the project as kind `app`, provide the canonical store domain, and select a development branch different from the project primary branch.
  </Step>

  <Step>
    Wait for the durable connect operation to create both project environments and managed PostgreSQL databases.
  </Step>

  <Step>
    Enter the development target values, save, and run verification; repeat with different production values.
  </Step>

  <Step>
    Resolve every launch check before treating the application as production-ready.
  </Step>
</Steps>

## 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](https://shopify.dev/docs/api/usage/versioning).

## Create target credentials

Create and manage apps in the [Shopify Dev Dashboard](https://shopify.dev/docs/apps/build/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](https://shopify.dev/docs/apps/build/dev-dashboard/app-automation-tokens) 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

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

## Common failures

<Warning>
  * 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
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Shopify hosting overview" href="/shopify/overview">
    What StackShift hosts, what remains in Shopify, who supplies credentials, and how app and storefront hosting differ.
  </Card>

  <Card title="Shopify app releases and rollbacks" href="/shopify/app-releases-and-rollbacks">
    How backend deployments are coupled to deterministic Shopify configuration and extension releases, retries, and compensation.
  </Card>

  <Card title="Shopify security and troubleshooting" href="/shopify/security-and-troubleshooting">
    Credential storage and isolation guarantees, launch-check interpretation, stable failure codes, and a production diagnosis sequence.
  </Card>
</CardGroup>