The Shopify dev environment checklist: Node versions, env files, Postgres

Before a Shopify app will run and install locally, four things have to be in place: the Node version the app expects, the env files it reads, a session store (Postgres), and a public HTTPS tunnel for OAuth and webhooks. Miss any one and you get a confusing failure — a version mismatch, a missing secret, a session error, or a callback that never resolves. This is the checklist, and ReDock — a free-while-in-alpha native macOS app — handles every item as part of its Shopify app development environment. (It’s for building apps, not managing a store.)

1. The right Node version

Shopify app templates pin a Node version, and running on the wrong one produces errors that look like your code’s fault but aren’t.

• Check engines.node in package.json. Shopify app scaffolds also commonly have a web/ subpackage with its own engines.node — the front end and back end can expect different versions.
• Run on that version, not your PATH default. Whatever Node you happen to have globally is irrelevant if the app pinned something else.

ReDock reads engines.node — including the web/ subpackage — and runs the app on the version it expects automatically, so this item is handled without you switching Node by hand. The stacks docs cover version detection.

2. Env files, detected and seeded

Shopify apps read configuration from env files: API key, API secret, scopes, app URL, and more. The usual failure is a missing or half-filled .env.

• Know which files the app needs — often a root .env plus template-specific ones.
• Seed them rather than copy-paste-and-guess from .env.example.

ReDock detects the env files your app needs and seeds them, so you’re not hunting for which keys matter before the app will boot. The first-site guide covers importing the app.

3. A session store (Postgres)

Shopify apps store sessions somewhere. If there’s no session store, OAuth completes and then immediately falls over because there’s nowhere to persist the session.

• Provision a database the app can use as its session store.
• Point the app’s config at it via the env values from step 2.

ReDock provisions a session Postgres so this is done for you — no manual createdb, no connection-string wrangling.

4. A public HTTPS tunnel

This is the one localhost can’t provide on its own. Shopify’s servers redirect OAuth to your callback and POST webhooks to a URL — neither can reach http://localhost.

• Expose the app at a real HTTPS URL so the OAuth callback resolves.
• Register that URL for webhooks so events actually arrive.

ReDock provides the public HTTPS tunnel, so OAuth and webhooks work against your local app. Shopify app development on localhost covers all four pieces together, and testing webhooks locally drills into the webhook half.

Running the checklist without doing it by hand

The point of the list isn’t to do each step manually every time — it’s to know what “a working environment” means so you can tell when something’s off. ReDock’s Shopify app environment covers all four automatically, and the MCP docs describe how the whole app is agent-operable if you want to drive setup through tools.

One honesty note, same as everywhere in ReDock: this is an environment for developing Shopify apps. It runs, exposes, and configures your app locally. It is not a store-management tool — Shopify MCP: what agents can and can’t do draws that line.

FAQ

What Node version does my Shopify app need?

Whatever engines.node specifies — check both package.json and any web/ subpackage, since they can differ. ReDock reads these and runs the app on the right version automatically.

Why does my app need Postgres locally?

For the session store. Shopify apps persist sessions, and without a database, OAuth completes but the session has nowhere to live. ReDock provisions a session Postgres for you.

Can I skip the tunnel if I’m just testing?

No. OAuth callbacks and webhooks come from Shopify’s servers, which can’t reach localhost. You need a public HTTPS URL — ReDock provides the tunnel.

---

Want this whole checklist handled for you? Download ReDock to ReDock and get a working Shopify app dev environment.