Shopify Theme Previews

FlightDesk can spin up a live shopify theme dev server for every branch of a Shopify theme repo. Each preview gets its own HTTPS URL backed by a real Shopify store, so reviewers can test theme changes without pulling the branch locally.

How It Works

The preview container runs shopify theme dev, which authenticates with your Shopify store and starts a local proxy server. Caddy exposes that proxy over HTTPS. Because the Shopify CLI connects outbound to Shopify's servers, no tunnel or URL registration is needed — the container just needs internet access and valid credentials.

Prerequisites

• Preview environments enabled for your project (see Preview Environments)
• Admin access to the Shopify store you want to preview against
• The Theme Access app installed on that store

Step 1: Install the Theme Access App

Theme Access generates a headless password the Shopify CLI can use without a browser login — essential for containers.

1. In your Shopify Admin, go to Apps → Search for apps
2. Search for Theme Access and install it (it's a free official Shopify app)
3. Once installed, open it and click Create password
4. Give the password a label (e.g. "FlightDesk previews") and copy it — you won't see it again

Step 2: Add Secrets to FlightDesk

In Project Settings → Secrets, add:

| Key | Value | |---|---| | SHOPIFY_STORE | Your store URL, e.g. mystore.myshopify.com | | SHOPIFY_THEME_PASSWORD | The Theme Access password you just generated |

These are encrypted at rest and injected into each preview container at spin-up. Every container gets its own isolated copy — multiple simultaneous previews work without any conflict.

Step 3: Configure Setup Commands

In Project Settings → Preview → Setup Commands:

npm install -g @shopify/cli @shopify/theme

This installs the Shopify CLI inside the container. If your theme has its own package.json dependencies (e.g. a build step), add those commands after:

npm install -g @shopify/cli @shopify/theme
npm install
npm run build

Step 4: Configure Processes

In Project Settings → Preview → Processes:

[
  {
    "name": "web",
    "command": "shopify theme dev --store $SHOPIFY_STORE --password $SHOPIFY_THEME_PASSWORD --port 9292 --host 0.0.0.0",
    "port": 9292,
    "primary": true
  }
]

What this gives you for a branch named new-homepage:

• https://new-homepage.preview.flightdesk.dev

The preview proxies to your live Shopify store with the branch's theme applied, including hot-reload when files change.

Troubleshooting

"Invalid password" or authentication error in logs

Double-check the value of SHOPIFY_THEME_PASSWORD in your project secrets — the Theme Access app shows the password only once. If you've lost it, generate a new one in the Theme Access app and update the secret, then restart the preview.

Preview loads but shows the wrong theme

The shopify theme dev command uploads your branch's theme files to Shopify as a development theme. If another preview is also running against the same store, they each get their own development theme slot and won't interfere with each other.

Hot-reload isn't working

Hot-reload uses a WebSocket connection. If your browser is blocking WebSocket connections to the preview domain, try a different browser or disable any extensions that interfere with WebSocket traffic.