A practical series

Shopify App Handbook

Nineteen short notes that take you from never having built a Shopify app to working on a real one. Written for people starting from zero — every term is explained before it is used, and every note ends with the traps that cost real time.

Start here

  1. Learn the pieces: read 01 → 09 in order. Each builds on the last. (Already know React? Start at 04.)
  2. Build something: work through 14, a complete app from start to finish. This is where it clicks.
  3. Ship it: read 10 → 13 when you are ready for a real server and real merchants.
  4. Going public? 15 → 17 are required for the Shopify App Store. Skip them for apps built for a single client.

Keep 18 open whenever something is not working.

Foundations
01 Shopify App Anatomy What a Shopify app actually is, what every folder and config file does, and how a request travels through them. 02 Shopify CLI Essentials The commands you run daily, and which ones can destroy a production database. 03 Routes, Loaders & Actions How file names become URLs, how a page gets its data, and how a form saves it.
Data
04 Shopify Auth & Sessions The two tokens everyone confuses, what a session really is, and the rule that stops one shop reading another's data. 05 Prisma & Your Database Designing tables, relations and cascades, migrations, and the read/write commands you need. 06 Shopify Admin GraphQL Asking Shopify for data and changing it — plus three silent failures that all return HTTP 200.
Building the interface
07 Forms & Submissions Validation, error display, loading states, and why Polaris fields submit nothing by default. 08 Shopify File Uploads The staged upload flow, why uploading through your own server breaks, and bulk uploads. 09 App Bridge & Polaris Components, modals, toasts and the resource picker — and how custom elements differ from React.
Put it all together
14 Build Your First App A complete Product Badges app, start to finish — every earlier note assembled into something that runs.
Running in production
10 Webhooks & Background Jobs Reacting to shop events and running scheduled work without duplicates or overlap. 11 Deploying a Shopify App The two deploys people confuse, Docker, safe migrations, and a go-live checklist.
Shipping to merchants
12 Shopify Dev Dashboard Organizations, apps, versions and dev stores — and how the dashboard stays in sync with the CLI. 13 Distributing Your App Custom install links for a client, or publishing to the Shopify App Store — step by step.
Public App Store apps
15 Compliance Webhooks The three privacy webhooks every App Store app must handle, and how they fit with keeping data on uninstall. 16 Charging for Your App Shopify App Pricing: plans, the hosted plan page, and checking payment without locking out paying merchants. 17 Theme App Extensions Putting your app on the storefront with app blocks and embeds — never by editing theme code.
Tools
18 Debugging Your App Where each kind of code logs, DevTools inside the admin, and a lookup table of common errors.
Going further
+ Shopify App Proxy Runbook Serving data to a storefront from your own server, so the theme depends on your app running.

The five mistakes that cost the most time

Collected from across the series. If you only remember a handful of things, make it these.

  • Unscoped database queries. A query without where: { shop } returns every shop's rows. Invisible while one shop is installed; a data breach when the second arrives. (04, 05)
  • Unread userErrors. A failed Shopify mutation still returns HTTP 200. Without checking, your code reports success while nothing saved. (06)
  • Forgetting to paginate. first: 50 looks perfect on a small test shop and silently truncates on a real one. (06)
  • The uninstall cascade. Deleting the session row on uninstall can erase everything that shop ever created. (04, 05)
  • Deploying only half. Code goes to your host; settings go to Shopify. Most changes need both. (11)
  • Treating an error as "unpaid". If a subscription check fails and you redirect anyway, you lock out a paying merchant. Only a successful empty answer means no plan. (16)
  • Assuming new permissions apply automatically. After you release a version with new scopes, every merchant must approve it in their own admin. (12, 13)

Your first week, in order

# set up
npm install
npx prisma generate
shopify app dev

# every new page
loader  → read data    (scope it by session!)
action  → write data   (check userErrors)
default → the UI

# before every production deploy
back up the database
shopify app info        # am I on the right app?
read the migration SQL
deploy code AND settings
open the app and click through
How to use these

Each note is self-contained and copy-paste friendly. They are written generically — myapp.com, db.widget — so they apply to any Shopify app, not one specific project.

One caveat

Shopify's APIs change every quarter. The concepts here are stable, but before copying an exact field name or mutation, check it against the docs for your pinned API version, or test it in shopify app graphiql first.