> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the public docs of Meridian for Shopify apps: hosting, billing (Plan Builder and the @the-meridian/sdk package), CRM, emails and automations for Shopify app developers.
> Start with these pages: Meridian MCP (https://help.the-meridian.ai/mcp-server.md) to connect a coding agent, AI coding agents (https://help.the-meridian.ai/ai-agents.md) for the agent skill, SDK quickstart (https://help.the-meridian.ai/sdk-quickstart.md), Running your app with the CLI (https://help.the-meridian.ai/cli-dev.md), Deployment (https://help.the-meridian.ai/deployment.md), and Errors (https://help.the-meridian.ai/errors.md) to look up an error code or message.
> Fetch one page at a time as Markdown (the page URL followed by .md), using the index in https://help.the-meridian.ai/llms.txt. llms-full.txt holds every page in one file of about 900 KB, so avoid loading it whole.
> With Meridian MCP connected, search these docs with docs_search and docs_get, and read live facts (feature and event keys, plan ids, environments, deployments, logs) from the MCP tools instead of guessing them.

# Recommended Shopify app setup and release order

> Recommended setup for a Shopify app on Meridian: one Shopify app, APP_URL on shopify app deploy, server before extensions, Shopify's security check.

None of this is enforced by Meridian, and none of it is a Meridian bug. These are the setup choices that cost the most time on real apps built on Meridian, most of them first seen during an App Store submission or a broken production release. Follow them from the start.

| Do | Instead of |
| - | - |
| [One Shopify app](#one-shopify-app-not-a-separate-dev-app), tested on a development store | A second "(Dev)" app in the Partner Dashboard |
| [Set `APP_URL`](#give-extensions-the-backend-url-when-you-deploy-them) when you run `shopify app deploy` | Relying on the value `shopify app dev` sets |
| [Release the server, then the extensions](#release-the-server-then-the-extensions), from the same commit | Deploying one and forgetting the other |
| [Remove the template's shop domain form](#remove-the-shop-domain-form-from-the-template) | Submitting the template's landing page |
| [Run Shopify's security check](#run-the-shopify-security-check-before-each-release) before each release | Finding the issues in App Review |

## One Shopify app, not a separate dev app

Use a single app in the Partner Dashboard for development and production. Test on a [development store](https://shopify.dev/docs/apps/build/stores/development-stores) with `meridian dev`, which runs the template's `npm run dev` (`shopify app dev`).

`shopify app dev` installs a **dev preview** of your local code on the development store you pick. Its app URL, configuration and extensions change on that store only, so the released version merchants run is untouched. A second app gives you nothing more, and it costs:

* **Duplicates on the storefront.** Each app has its own customer account pages and its own `/apps/...` [app proxy](https://shopify.dev/docs/apps/build/online-store/app-proxies). A store with both installed shows both.
* **Its own Shopify approvals.** Protected customer data access is granted per app, so the dev app misses what the real one was approved for, and code that works in production fails in development.
* **Stale sessions.** A session the other app left in your session table can make requests fail with empty 500 errors, which are hard to trace back to it.
* **No Meridian behind it.** A Meridian app holds one Shopify client ID and secret (see [Shopify API credentials](https://help.the-meridian.ai/app-settings.md#shopify-api-credentials)), so installs of the other app get no contact capture, no billing and no CRM.

Keep `automatically_update_urls_on_dev = true` in `shopify.app.toml` so the dev preview points at your local tunnel. The production URLs stay those of your Meridian [production environment](https://help.the-meridian.ai/environments.md).

## Give extensions the backend URL when you deploy them

An extension that calls your server (a customer account page, a checkout extension) usually reads the URL from `process.env.APP_URL`. Shopify CLI only defines that variable while `shopify app dev` runs. `shopify app deploy` builds the extensions with whatever your shell has, so without it production extensions ship with `undefined` as their backend and fail on every store.

Set it to your production URL when you deploy, either the [default domain](https://help.the-meridian.ai/default-domain.md) or your [custom domain](https://help.the-meridian.ai/custom-domain.md):

```bash theme={null}
APP_URL=https://your-app.the-meridian.app shopify app deploy
```

Put it in the script or CI job that runs `shopify app deploy`. The Meridian variables of your environment (see [Environment variables](https://help.the-meridian.ai/secrets.md)) reach your server, never the extensions Shopify builds on your machine.

## Release the server, then the extensions

A release is two deploys: Meridian builds and runs your **server**, and `shopify app deploy` publishes your **extensions and app configuration** as a new app version. Neither one does the other. When only one runs, production ends up with a new server and old extensions (or the reverse), which is how one app ended up running a recent server with extension version 1.0.0.

Release in this order, from the same commit:

1. **Deploy the server on Meridian** and wait until the deployment shows **Succeeded** (see [Deployment](https://help.the-meridian.ai/deployment.md)). On an Enterprise app, bring it through Staging first (see [Bringing a build forward](https://help.the-meridian.ai/environments.md#bringing-a-build-forward)).
2. **Deploy the extensions** from that commit, with its SHA as the version message so you can match the two later:

   ```bash theme={null}
   APP_URL=https://your-app.the-meridian.app shopify app deploy --message "$(git rev-parse --short HEAD)"
   ```

Server first, because a released app version reaches every store within minutes: an extension that calls an endpoint the live server doesn't have yet fails until the server catches up. For the same reason, keep each server release compatible with the extension version that is live while stores upgrade.

Rolling back works the same way, twice. A Meridian [rollback](https://help.the-meridian.ai/deployment.md#rollback) moves the server only. To move the extensions back, release the previous app version from the Dev Dashboard or with `shopify app release`.

## Remove the shop domain form from the template

Shopify's React Router app template serves a landing page at `/` with a **Shop domain** field and a **Log in** button (`app/routes/_index/route.tsx`). It is there for local testing. In production it breaks App Store [requirement 2.3.1](https://shopify.dev/docs/apps/launch/shopify-app-store/app-store-requirements): an app must not ask for a `myshopify.com` URL or a shop's domain, because installs start from Shopify.

Before you submit, replace that route with a plain page about your app, or a redirect to your App Store listing, with no form. Merchants never need it: they open your app from the Shopify admin, and the template's `authenticate.admin` handles the rest.

## Run the Shopify security check before each release

Shopify CLI scans your app for known security issues:

```bash theme={null}
shopify app security check
```

It runs a fixed set of checks on its own, then prints instructions for your coding agent to review what code inspection alone can't decide. Most of its checks are written for the React Router template. Run it on every release, and pass `--blocking high` in CI to fail the build on a high-severity finding. See Shopify's [app security checks](https://shopify.dev/docs/apps/build/security/app-security-checks).

On one app it found that forwarded webhooks were verified without their shop and topic. If you receive [forwarded webhooks](https://help.the-meridian.ai/sdk-webhooks.md), use SDK 3.0 or later and verify them with `verifyMeridianWebhookDetailed`, which also returns the verified shop.

## Related

* [Running your app](https://help.the-meridian.ai/cli-dev.md): `meridian dev` and the developer database
* [Billing from local development](https://help.the-meridian.ai/sdk-credentials.md#billing-from-local-development)
* [Deployment](https://help.the-meridian.ai/deployment.md): the build, the container port, the release command
* [Environments](https://help.the-meridian.ai/environments.md): Development, Staging and Production


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.