Skip to content
Tutorials Center
My learning

Topics

Lesson 46 of 55 ยท Testing, Deployment and Operations

Deploying Your App

Deploy a Shopify app the right way: host the server, set environment variables, point the TOML URLs at production, and release app versions with shopify app deploy.

When you run shopify app dev, the CLI starts your server on your laptop, opens a tunnel so Shopify can reach it, and quietly rewrites URLs in a development copy of the app. None of that exists in production. To go live you have to do two separate things, and mixing them up is the most common deployment mistake: you host your server somewhere with a stable HTTPS address, and you deploy an app version to Shopify so it knows your configuration and extensions.

This lesson separates the two, lists what a hosting platform must provide, explains the environment variables and URLs, and shows a safe release routine. The commands and configuration are read-only (they need a real Shopify account and host). The runnable examples are stand-ins: a configuration validator and a release-state simulator written in plain JavaScript. Command names and flags evolve, so confirm them with shopify app deploy --help and the current CLI documentation. The configuration file is covered in App Configuration with shopify.app.toml.

Two things called "deploy"

flowchart LR
  subgraph "You"
    C["Code + shopify.app.toml<br/>+ extensions"]
  end
  C -->|"1. host the server<br/>(your platform)"| H["Your server<br/>https://app.example.com"]
  C -->|"2. shopify app deploy"| V["App version<br/>on Shopify"]
  V -->|"release"| L["Live for merchants"]
  H <-->|"requests"| L

Hosting runs your backend. shopify app deploy publishes configuration and extensions to Shopify.

Hosting your server shopify app deploy
What moves Your web app, routes, jobs App configuration and extension code
Where it runs Your platform (a container, a VM, a managed service) Shopify's infrastructure (admin UI, checkout, functions, theme blocks)
Triggered by Your CI/CD pipeline You or your pipeline, via the CLI
Rolled back by Redeploying the previous build Releasing an earlier app version

Extension code (a checkout UI extension, a function, a theme app extension) is not served from your server. It is bundled and uploaded to Shopify by shopify app deploy. Your server only handles the embedded admin pages, API routes and webhooks. Because the two halves update separately, a release plan has to think about which order is safe; we come back to that below.

What your host must provide

You can run the app on many kinds of platforms: a container service, a platform-as-a-service, a virtual machine, or a serverless runtime. The generated template includes a Dockerfile, which makes any container host a straightforward choice. Whatever you pick, check this list first:

  • A stable public HTTPS URL with a valid certificate. Shopify will not call plain HTTP, and the URL must not change on every deploy.
  • A long-running Node process or a runtime that suits your session and job design. Serverless platforms work, but each invocation may open a database connection and cannot keep an in-memory queue, so use a pooled database and an external queue (Databases and Session Storage in Production).
  • A production database reachable from the server.
  • A place for secrets (the host's secret manager), so keys never enter Git.
  • Logs you can read and a way to restart the process.
  • Region and latency. Your embedded pages load inside the admin, so a server close to your merchants and to Shopify makes the app feel faster.
  • Enough headroom for webhook bursts, since a flash sale delivers many events at once (Monitoring, Logging and Scaling).

Free tiers that put a service to sleep are fine for tutorials, not for production: a cold start can exceed the webhook timeout, and Shopify may then retry and eventually remove the subscription.

Environment variables

The template reads its configuration from the environment. The names below match the generated template; check yours.

Variable Meaning
SHOPIFY_API_KEY The app's client id (public)
SHOPIFY_API_SECRET The app's client secret (secret)
SHOPIFY_APP_URL Public HTTPS URL of your server
SCOPES Comma-separated access scopes
DATABASE_URL Connection string for the production database
NODE_ENV production
PORT The port the process must listen on (many hosts set this)

The API secret signs every webhook and verifies every session token. If it leaks, an attacker can forge both, so rotate it in the Dev Dashboard if there is any doubt, then update the host's secret and redeploy. Never print it in logs and never ship it to the browser. See App Security Checklist.

Development and production should be two different apps in your Partner or Dev account (each with its own key and secret), so test installs and test URLs never touch the real listing. The CLI supports several config files for this, for example shopify.app.toml for one app and shopify.app.production.toml for another, and shopify app config link connects a local file to an existing app.

URLs in the TOML

The URLs in your configuration tell Shopify where your server lives. In production they must match your real host:

TOML
# shopify.app.production.toml (excerpt, read-only)
client_id = "0123456789abcdef0123456789abcdef"
name = "Low-Stock Alerts"
application_url = "https://alerts.example.com"
embedded = true

[auth]
redirect_urls = ["https://alerts.example.com/api/auth"]

[webhooks]
api_version = "2026-07"

  [[webhooks.subscriptions]]
  topics = ["app/uninstalled"]
  uri = "/webhooks/app-uninstalled"

Common mistakes: leaving a trycloudflare.com tunnel URL from development in the file, using http://, a trailing-slash mismatch in the redirect URL, or a mismatch between application_url and the host your server believes it is. An embedded app whose URL is wrong shows a blank iframe or a "refused to connect" error, which is hard to diagnose unless you look at the browser console.

Validate configuration before you ship

A deploy that starts with a missing secret fails in confusing ways: sessions cannot be verified, so every page redirects in a loop. The cheapest protection is a startup check that refuses to boot with bad configuration and explains why. The stand-in below shows one. It is not part of Shopify; you would write something similar in your server's entry file, using a library of your choice for schemas.

Node.js Validating production environment variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In a real server you would call the check at boot and process.exit(1) when it returns problems, so the platform's health check fails and the bad release never takes traffic.

Building and starting the server

The generated template has scripts for building and running. A typical production routine on your host, simplified:

Terminal
npm ci                      # install exactly what the lockfile says
npm run build               # compile the React Router app
npx prisma generate         # generate the database client
npx prisma migrate deploy   # apply pending migrations (once per release)
npm run start               # start the server

Run migrations once per release, not in every instance, to avoid two instances racing. Many teams run the migration as a separate release command and then start the instances. The template's Docker setup bundles a combination of these steps; read the Dockerfile and package.json scripts of your generated project instead of trusting a blog post, because they change between template versions.

Releasing an app version

shopify app deploy packages your TOML configuration and every extension into an app version, uploads it, and by default releases it to merchants. In read-only form:

Terminal
# Link to the production app (once)
shopify app config link

# Create and release a version, with a readable name and message
shopify app deploy --config production \
  --version "2026-10-30-low-stock" \
  --message "Add digest emails"

# Create a version without releasing it, then release later
shopify app deploy --no-release
shopify app release --version "2026-10-30-low-stock"

Facts worth remembering:

  • A version is an immutable snapshot. To change anything you create a new version.
  • Releasing makes the version active for all installs. Configuration changes that need new scopes trigger a consent prompt for merchants (Managed Installation and Access Scopes).
  • You can roll back by releasing an earlier version. This reverts configuration and extensions, not your server or database.
  • CI usually runs shopify app deploy --force with a token from the Dev Dashboard instead of an interactive login. Store that token as a CI secret.

Order matters

Your server and your app version are loosely coupled, so a release can break if the two are briefly out of step. For example, an admin extension that calls a new route will fail if the extension is released before the server has that route. The safe order for most changes is:

  1. Deploy additive server changes first (new route, new column nullable). Old extensions keep working.
  2. Release the new app version (extensions, TOML).
  3. Clean up later (remove old routes) after merchants have moved to the new version.

The stand-in below models this with two timelines and a compatibility rule. It is a teaching aid, not Shopify's behavior.

Node.js Release order: server first or extension first?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A release checklist

Before you press the button:

  1. All tests pass in CI (Testing Shopify Apps).
  2. The environment check passes with the production variables.
  3. Database migrations are backward compatible and applied.
  4. Server deployed, health check green, logs quiet.
  5. shopify app deploy run from a clean checkout of the same commit.
  6. Smoke test on a development store: install, open the app, trigger one webhook, use each extension.
  7. Watch error rates and webhook failures for the first hour; know which version to release if you must roll back.

For public apps there is one more gate: changes to listing content and some configuration are reviewed, which is why App Store Requirements and Review belongs in your routine.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which part is uploaded to Shopify by shopify app deploy?

    The command publishes an app version containing configuration and extensions. Your backend is hosted separately on your own platform.
  2. 2. Why should development and production be separate apps?

    Separate apps have separate keys, secrets and URLs, so experiments cannot break production.
  3. 3. What is the safest order when an extension starts calling a brand-new server route?

    If the route exists before the extension needs it, there is never a moment when the extension calls something missing.
  4. 4. What does releasing an earlier app version roll back?

    A version is a snapshot of configuration and extensions. Server and database rollbacks are your own responsibility.
  5. 5. Why validate environment variables at startup?

    Missing or wrong values, such as a development URL or an unset secret, cause redirect loops and silent failures. Failing early keeps a broken build out of traffic.

Summary

  • Hosting your server and deploying an app version to Shopify are two different steps with different rollbacks.
  • Your host needs stable HTTPS, a production database, secret storage, logs and room for webhook bursts.
  • Configure SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SHOPIFY_APP_URL, SCOPES and DATABASE_URL from the host's secrets, and validate them at boot.
  • Use a separate app for production with real URLs in its TOML file, never a development tunnel.
  • Run migrations once per release, deploy additive server changes before releasing the version, and keep a rollback plan.

Next, learn how to see problems before merchants do in Monitoring, Logging and Scaling.