Apps Overview and Scaffolding

Source: Shopify docs: About app distribution

Public distribution is for software sold to many merchants through the Shopify App Store. It requires the App Store requirements and review, and it is the only method that Shopify’s own billing can charge for. Custom distribution is for software written for one merchant or one Plus organization: Shopify generates an install link and the developer sends it to the store owner. A custom app can be installed on several stores only when they belong to the same Plus organization, and that option can be switched off when the link is generated (the setting is called Allow multi-store installs for one Plus organization). Apps whose App Home is a Shopify-hosted UI extension can use custom distribution only.

Two older app types can no longer be created: private apps (deprecated January 2022, automatically converted to custom apps on 2023-01-20) and unpublished apps (deprecated 2019-12-09). The admin-created custom app, built under Settings, Apps, Develop apps inside the Shopify admin, is a third legacy form: existing ones keep working, new ones cannot be created, and Shopify directs new work to the Dev Dashboard or to Shopify CLI.

Pocket Coffee is one merchant, so the order logger and the Coffee Club discount only ever install on its own store: custom distribution fits. If the same developer later sells the roast-date badge to other roasters, that part becomes a separate public app. The flowchart condenses the choice.

Every app of an organization appears in the Dev Dashboard (dev.shopify.com/dashboard), whichever tool created it. The Dev Dashboard was relaunched on 2026-09-25 as the home for apps, stores, collaborator access and app health; the Partner Dashboard is still used for App Store submission and quality checks. There are two ways to create an app.

An app created in the Dev Dashboard can be moved under CLI management later: scaffold an extension-only project with shopify app init, run shopify app config link, choose to connect it to an existing app, and check the imported shopify.app.toml. From then on a change is made in the file and released with shopify app deploy. The reasons Shopify gives are version control of the configuration, access to extensions and Functions, settings that only the CLI manages (handles), and managing staging and production apps from one project.

An app that acts only on stores of the developer’s own organization needs no merchant install: it authenticates with the client credentials grant using its client ID and secret and receives a token valid for 24 hours. This is the usual choice for an integration between Pocket Coffee’s own back office and its store.

Source: Shopify docs: Create apps using the Dev Dashboard

React Router (Node.js) is Shopify’s recommended stack and the only app template shopify app init offers apart from the extension-only one. Shopify’s official libraries cover other stacks. On 2026-08-26 Shopify released official PHP (shopify/shopify-app-php on Packagist) and Python (shopifyapp on PyPI) packages at version 1.0, which provide request verification, token exchange (including client credentials and refresh) and an Admin GraphQL client with retries; the older shopify-api-php and shopify_python_api libraries are deprecated. There is no PHP or Python app template, so those projects scaffold their own code, and the CLI remains available for configuration and extensions.

Source: Shopify docs: shopify app init

Both forms from the CLI help follow. The first creates a new app non-interactively; the second links a new project to an existing app and uses the empty template.

Source: Shopify docs: shopify app init

The same command accepts a template URL, which is how the React Router template is referenced in Shopify’s own package documentation:

Source: Shopify docs: Shopify App package for React Router

An extension-only app can also get a developer-hosted App Home page: set application_url to the hosted URL. That is the route to public distribution, because the Shopify-hosted App Home UI extension is restricted to custom distribution.

Source: Shopify docs: Build an extension-only app

The old Remix template is no longer offered: the --template option of CLI 5.0.0 names only reactRouter and none (plus URLs). Apps created from the Remix template keep working, and the migration is described later on this page.

The scaffolded project is connected to the Dev Dashboard app it created. The first shopify app dev or shopify app config link updates shopify.app.toml to reflect the linked app (the template ships it with an empty client_id). The generated project also handles authentication: the template performs the token exchange so the developer never writes an OAuth flow. Once the project exists, cd into it and run shopify app dev (see the development loop below), press p to open the preview URL, and click Install app on the dev store. The home page of the template then offers a Generate a product button that runs a productCreate mutation.

The login that app init needs creates a developer session, and no account or login is used while writing this page, so shopify app init was run only as far as its refusal. In a non-interactive shell it stops with: "To run this command, log in to Shopify. Authorization is required to continue, but the current environment does not support interactive prompts." and creates nothing. It also reports missing flags (--name or --client-id, --organization-id or --client-id, and --flavor) before authenticating when they are absent. All the project-level steps (typecheck, production build, lint, running the built server with placeholder values, validating configuration) were executed on a copy of the public template, and are reported where they appear below.

Source: Shopify/shopify-app-template-react-router

The repository also carries development-assistant files (AGENTS.md, CLAUDE.md, .mcp.json for the Shopify Dev MCP, a Gemini extension and Cursor settings) and a CHANGELOG.md. The template’s changelog is the quickest way to see what changed between scaffolds: 2026.10.09 moved the API version to 2026-10; 2026.09.03 pinned React Router to 7.18.2 because 7.18.3 tightened origin validation of actions and made every action return 400 Bad Request under shopify app dev and behind TLS-terminating proxies, and forced qs to ^6.16.0 to clear two advisories; 2025.12.11 added the refresh-token fields and the expiringOfflineAccessTokens flag.

Every other file imports from app/shopify.server.ts. It calls shopifyApp() once and re-exports the pieces.

Source: Shopify/shopify-app-template-react-router: app/shopify.server.ts

The first import selects the Node adapter, which supplies the Web fetch and crypto implementations the package expects. The options and what they do:

Source: Shopify docs: shopifyApp

What the object offers: authenticate.admin (for requests from the app’s UI or from admin extensions), authenticate.webhook, authenticate.public, authenticate.flow, authenticate.fulfillmentService and authenticate.pos; unauthenticated.admin and unauthenticated.storefront for background work that has an offline session; login for the shop-domain form; registerWebhooks; addDocumentResponseHeaders; and sessionStorage. authenticate.admin returns the session, an admin client whose only method is graphql, a billing helper, a cors helper, the decoded sessionToken, a redirect helper and scopes (with query, request and revoke). The Admin client has no REST method: the package removed REST, as the migration section explains.

app/routes.ts is one line, export default flatRoutes();, so file names map to URLs: app._index.tsx is /app, app.additional.tsx is /app/additional, webhooks.app.uninstalled.tsx is /webhooks/app/uninstalled. app.tsx is the layout route of every page below /app:

Source: Shopify/shopify-app-template-react-router: app/routes/app.tsx

The layout does four jobs. Its loader calls authenticate.admin(request), which validates the ID token, performs the token exchange and, when there is no session, redirects through the right authentication flow. AppProvider loads App Bridge and the Polaris web components script and needs the client ID, which the loader passes down because the browser cannot read process.env. s-app-nav declares the navigation menu in the admin sidebar, built from s-link elements (the older documentation shows NavMenu from App Bridge React with Link children; both exist). The ErrorBoundary and headers exports are required: Shopify needs React Router to catch some thrown responses so their headers survive, and the boundary helpers do that. Every route that calls authenticate.admin must export headers the same way.

The other routes:

Source: Shopify docs: Shopify App package for React Router

Webhook routes must not be nested under the app layout route, because Shopify calls them without an admin session. That is why their file names start with webhooks. and not with app..

Pocket Coffee wants the line "order placed" with the order number and the total in its log. That needs a webhook subscription in the configuration and a route to receive it. The subscription asks for only the three fields the handler reads:

Source: Shopify docs: App configuration

and the route, app/routes/webhooks.orders.create.tsx:

Source: Shopify docs: authenticate.webhook

The orders/create topic needs the read_orders scope, so the scope list in shopify.app.toml must contain it (the configuration example below does). The route was added to a copy of the template and run: npm run typecheck passed, the production build passed, and the built server was started with placeholder values (SHOPIFY_API_KEY of 32 zeros, a made-up secret, SHOPIFY_APP_URL=https://pocket-coffee-app.example.test). A hand-signed request, with a synthetic payload and the made-up secret, returned 200 and logged order placed #1001 total 38.80 EUR (ORDERS_CREATE from pocket-coffee-dev.myshopify.com); the same signature on a changed body returned 401. The topic arrives in the enum form ORDERS_CREATE, not orders/create. No request left the machine and no real order or store was involved.

prisma/schema.prisma defines one model, Session, with the columns id, shop, state, isOnline, scope, expires, accessToken, userId, firstName, lastName, email, accountOwner, locale, collaborator, emailVerified, and, for expiring offline tokens, refreshToken and refreshTokenExpires. The datasource is file:dev.sqlite. SQLite is fine for a single running instance, which is the case for Pocket Coffee’s one store, but a multi-instance deployment needs another Prisma datasource or a different session-storage adapter (MySQL, PostgreSQL, Redis and MongoDB adapters exist). If a route fails with "The table main.Session does not exist", run the setup script, which is prisma generate && prisma migrate deploy. The .env files, prisma/dev.sqlite and the .shopify directory are git-ignored by the template; the lockfiles are ignored too, which conflicts with Shopify’s recommendation to commit the lock file of the package manager, so teams usually remove those lines.

vite.config.ts contains two non-obvious pieces. It replaces the HOST variable the CLI sets with SHOPIFY_APP_URL, because a HOST value breaks the Vite server (the comment says the CLI will stop passing it in a later major release); and it picks the hot-module-reload settings from the host name, WebSocket on port 64999 for localhost and secure WebSocket on FRONTEND_PORT (default 8002) through port 443 for a tunnel. The server listens on PORT (default 3000).

.graphqlrc.ts configures GraphQL code generation for the Admin API version 2026-10 over the files below app/ and adds one project per extension that has a schema.graphql. .npmrc sets engine-strict=true, which makes an old Node.js fail the install, and shamefully-hoist=true, which recent npm versions report as an unknown project setting; the warning is harmless. The Dockerfile starts from node:22-alpine, installs OpenSSL, runs npm ci --omit=dev, builds the app and starts it with npm run docker-start. The template’s own workflow runs typecheck, ESLint, prisma validate and the build on Node 22 and 24 with npm, Yarn and pnpm.

Source: Shopify docs: Scaffold an app

The webhook status codes follow Shopify’s rule that an invalid HMAC must receive 401 Unauthorized; a request without the Shopify headers is rejected earlier with 400.

Source: Shopify/shopify-app-template-react-router: Upgrading from Remix

Shopify publishes two example migration branches (the template itself, and the QR code example app) and a step list. In order:

The login route is the smallest worked case:

Source: Shopify/shopify-app-template-react-router: Upgrading from Remix

After the swap, three template changes are worth adopting even though the guide predates them: set future.expiringOfflineAccessTokens and add the two refresh-token columns to the Prisma Session model (required for public apps from 2027-01-01), bump apiVersion, and move @shopify/api-codegen-preset and .graphqlrc.ts to the React Router package. The migration was not executed here, because it needs an existing Remix app and the codemod; the steps above are Shopify’s, and what this page verified is the target: the resulting template type-checks, builds and serves as described in the previous section.

The following file configures every section at once, using the placeholder client ID of 32 zeros and the reserved test domain example.test. It is a custom-distribution app that reads products and orders, can ask for customer access later, subscribes to three kinds of webhooks, serves an app proxy page at /apps/coffee on the storefront, and links to a preferences page.

Source: Shopify docs: App configuration

This file was placed in a project together with the Pocket Coffee discount extension and shopify app build --no-input was run: the CLI validated the configuration offline, built the extension and printed pocket-coffee-tools built!. The file has not been deployed: deploying needs a login. The compliance subscription is only mandatory for apps distributed in the App Store; a custom app may keep or omit it, and the template ships it commented out for that reason.

When scopes change in a new app version, they are not applied to existing installs automatically; merchants approve the new scopes the next time they open the app. Read scopes are implied by write scopes, so request write_products alone if the app needs both.

direct_api_mode (online or offline; default online) chooses which access token Direct API access uses. The local validator only accepts those two values. embedded_app_direct_api_access (a boolean, default false) enables Direct API access, which lets the app’s front end call the Admin GraphQL API with each request authenticated by App Bridge.

redirect_urls (required, an array of valid URLs) are the places users are sent after the authorization code grant. At least one must exist before the app is made public. The local validator requires the key: without it the build reports [auth.redirect_urls]: Required.

Configures OAuth 2.0 for the Customer Account API. redirect_uris (required) are the URLs customers return to after login, javascript_origins (optional, each with protocol and domain) do not currently enable CORS, and logout_urls (optional) are used for OpenID Connect logout. Apps that authenticate with their own client ID this way are public clients using PKCE and receive no refresh token; renewal repeats the authorization flow with prompt=none.

api_version (required) is the API version used to serialize webhooks. Each entry has:

A subscription declared in the TOML file is app-specific (one for every shop that installs the app, synchronized on every deploy). A subscription registered in code is shop-specific and is only refreshed when afterAuth runs, which is rarely during development; the template’s guidance is to declare webhooks in the TOML file. Webhooks created by hand in the Shopify admin fail HMAC validation because they are not signed with the app’s secret.

api_version (required) is the version used to validate and run subscription queries. Each has handle (required, alphanumeric, _ and -, up to 50 characters), topic (for example Product), actions (create, update, delete), uri, and optional triggers (field paths that narrow update deliveries), query (a GraphQL Admin operation whose result becomes the delivery data) and query_filter. Next Gen Events became generally available with API version 2026-10 and are covered with webhooks on a separate page.

Source: Shopify docs: App configuration

shopify app build --no-input validates shopify.app.toml against a schema before building, with no login. The following changes were made to the file above, one at a time, and the outcome recorded:

The template’s untouched shopify.app.toml fails the same check: [auth]: Required, [application_url]: Valid URL is required and [embedded]: Boolean is required, which shows that client_id = "" and a short file are only valid after shopify app config link (or app dev) has filled the rest in.

Besides shopify.app.toml, a project can have shopify.app.<config-name>.toml files, each linked to a different app on Shopify. The recommended layout keeps the default shopify.app.toml for the shared development instance and adds named files for staging and production.

Source: Shopify docs: Manage app config files

config link flags include --client-id (required when non-interactive), --file-name and --force (overwrite without prompting). Shopify notes that not every configuration file needs to be committed: depending on the workflow, personal development configurations can be git-ignored and only the production one kept. shopify app config push no longer exists: configuration is released together with extensions by app deploy. app config link, use, pull and validate need a login, and validate and info run in a non-interactive shell stop with a message that app config link requires additional flags in non-interactive terminal environments when the project has no linked app.

Source: Shopify docs: App structure

(The repository stores a Liquid template, shopify.web.toml.liquid, with the package manager filled in on scaffolding, and a name = "React Router" key; the lines above are the rendered result for npm.)

If the frontend and the backend are separate processes, each gets its own shopify.web.toml; the CLI starts both and expects the frontend to forward backend traffic to the port in BACKEND_PORT. A background process is for other long-running work. The CLI provides these variables to every process: SHOPIFY_API_KEY (the client ID), SHOPIFY_API_SECRET, HOST and APP_URL (the URL stores load), PORT (and FRONTEND_PORT, SERVER_PORT or BACKEND_PORT depending on the role), and SCOPES. web_directories in shopify.app.toml lists exactly where to look, and prevents a file being loaded twice through a symlink.

The root package.json of the template declares "workspaces": { "packages": ["extensions/*"] }, so one install covers the app and every extension, and each extension carries its own package.json. Shopify recommends committing the lock file of the package manager. The CLI builds UI extensions with ESBuild from an entry file named index.{ts,js,tsx,jsx} in the extension directory or src/; Functions run the build.command of their TOML file and expect a Wasm file at dist/index.wasm unless build.path says otherwise; a theme app extension is checked with Theme Check on build.

Source: Shopify docs: Select a networking option for local development

-s/--store selects the dev store (it must be a development or Plus sandbox store), -c/--config and --client-id select the configuration or app, --reset forgets the saved organization, app and store, --no-update uses the URL in the TOML instead of an autogenerated one, -t/--theme and --theme-app-extension-port serve a theme app extension, --checkout-cart-url and --subscription-product-url set preview resources, --store-password supplies the storefront password, --notify reports file changes to a file or URL, --unsafe-validation lets dev continue after eligible version-validation failures, and --skip-dependencies-installation is deprecated in favour of workspaces.

When app dev is stopped, the dev preview stays on the store with the app’s configuration and extensions. shopify app dev clean (or Clean dev preview in the Dev Console in the admin) restores the active released version, and anything that exists only in the preview is deleted: a Discount Function added during dev and the discounts that reference it, a UI extension placed in the checkout editor, a metaobject definition declared only in the preview. A team shares one development app instance (the default shopify.app.toml); each developer uses a personal dev store so previews do not collide.