Shopify Local Development: Setup, Workflow and Fixes

You're two hours into a theme change, the preview finally loads, and a teammate's work is staring back at you instead. Or your preview looks perfect, then checkout fails the first time a real payment provider touches it. That's the usual shape of Shopify local development problems. Your files are local, but your store data, preview state, webhooks, and checkout aren't. Once you treat that shared, remote half as engineering to design and clean up, most of the surprise failures stop.

Set Up Shopify CLI and Connect a Development Store

Shopify CLI only previews the store it is connected to. Point it at nothing, or at a development store another session already owns, and the preview fails before your theme or app code is even in question. I connect the store first.

The six setup steps

1. Install Node.js and a package manager. Use a current Node.js LTS release with npm, pnpm, or Yarn. The CLI depends on that toolchain to install and run.
2. Install Shopify CLI and confirm the version. Install the latest CLI globally, then check the reported version so the team is on one known release.
3. Create or open a development store. Do this in the Partners or Dev Dashboard. The store holds the preview, so choose the project store before you connect, not a store already in use.
4. Scaffold the project. Run shopify theme init for theme work or shopify app init for an app, so the file structure and config match what the CLI expects.
5. Connect and start the preview. Run shopify theme dev against that development store, or shopify app dev for an app. The Shopify CLI documentation describes shopify theme dev as creating a live-reloading development theme and shopify app dev as watching local app changes.
6. Open the preview URL on desktop and mobile. Products, collections, and cart should load from the store's own data. Placeholder content means the session is not on the catalog you intended.

Why a development store fits the job

A development theme is temporary and hidden. You can exercise product, collection, cart, and customer states without editing the published theme. That split is the point of the environment: local files, store-backed shopper context, published theme left alone.

The capacity is enough for serious QA, with one hard limit. The Shopify development stores documentation states that a development store can process an unlimited number of test orders, support an unlimited number of unique products, and create up to 10 custom apps. You can model a large catalog and repeat checkout scenarios. Plan custom app installs around that cap of 10.

How you structure the store is a separate choice from the CLI login. Our guide to a Shopify development store covers the store side of the setup. A healthy first run ends with three checks: a working preview URL, live store data in the storefront, and a published theme that nobody changed.

Practical rule: If the preview won't load, verify the connected store first, before you debug code that may not be broken.

Which Command Fits Each Project Type

Shopify local development is cloud-connected, not a local replica. Your editor, file watcher, and build tooling run on your machine. Store data, APIs, checkout behavior, and platform services come from Shopify. The Shopify CLI reference describes development stores as testing environments for building and testing apps and themes in a realistic Shopify environment without affecting a live store. Every command choice flows from that split.

Shopify CLI commands by task

Read the table by risk, not just by function. Theme work is safe to iterate on because the development theme stays unpublished, and it doesn't count toward a store's theme limit. App work is different: shopify app dev previews your changes without deploying a new production version, but that preview lands on a shared store, where it can displace a teammate's.

Headless work shifts the risk again. Hydrogen runs locally, yet it still depends on store credentials and remote data, so a wrong environment file gives you a convincing storefront built on the wrong catalog.

Pick the command by what you're changing, then check where its output lands before you run it.

That one habit, confirming the target store and preview before pressing enter, prevents most cross-contamination between developers. Deployment stays a separate, deliberate step either way.

Release Gate Before Anything Goes Live

A tax rule can look correct in preview. Totals add up, a stakeholder approves, and the change ships. The first real order then fails once the live payment provider connects, because the preview never ran that path. Development stores are password-protected and cannot process real transactions through active payment providers. A clean preview does not prove a clean launch.

A release gate is only useful if it is explicit and measured. A verbal all-clear is not one. Teams that track DevOps metrics that matter to employers already refuse an unmeasured handoff. On Shopify, that standard is concrete: every item below is checked, and the approver is named on the release.

This checklist marks where preview confidence stops and live verification has to start.

The release gate checklist

• Keep the development theme unpublished: Shoppers stay on the live theme until you deliberately publish or deploy the change.
• Review desktop and mobile previews: Layout and tap targets fail differently on a phone, so check both viewports before sign-off.
• Test theme settings and app blocks: Settings a merchant can change are the ones that break your assumptions about layout and content.
• Confirm a clean Git diff: Only the intended files should ship. Drop anything that arrived from another branch.
• Get stakeholder sign-off: Record who approved, so a rollback has a named owner.

What the preview cannot prove

Six flows need a separate staging run with the provider in test mode: tax calculation, shipping rates, payment authorization, email notifications, subscriptions, and checkout extensibility. Each one changes once live credentials and a real payment provider are in the path. Skip them and the store's first paying customer becomes the test.

The short walkthrough below shows how a preview session behaves day to day. Use it to see which of those six flows your current gate still never touches.

Deploy only when every gate item is checked and the approver is recorded with the release. A gate you can skip under time pressure is not a gate.

Team Previews and the Symptoms They Cause

Your machine is the only isolated part of this workflow. Shared dev stores, credentials, and preview state are where team failures happen. One developer's session can overwrite another's theme files or produce a preview that misleads both of them. I would design the environment before adding a second developer, not after the first collision.

Environment rules that hold up

Use one store or one development theme per branch or feature. Name each one so owner and branch are obvious at a glance, something a teammate can read without asking. Seed the store deterministically so a bug reproduces on any machine, and write a teardown rule for stale stores before they pile up.

Scripted lifecycle management is now practical. The Shopify CLI changelog entry on dev store commands notes that Shopify CLI 4.8 introduced terminal commands to create, list, inspect, and delete development stores, alongside a limit of 250 development stores per organization. That ceiling turns cleanup from tidiness into governance. Script provisioning and resets, then delete on a schedule.

The sharpest trap is app preview state. app dev installs a developer preview on the connected store and can replace another developer's preview until app dev clean runs. On a shared store, that's not a quirk, it's a daily coordination problem.

Team preview symptoms, causes and fixes

Notice that none of these fixes is a code change. They're naming conventions, isolation rules, cleanup schedules, and one cleanup command run at the right moment. Write the rules down once, put them in the repo, and enforce them in review. A team that depends on everyone remembering the etiquette will keep rediscovering the same symptoms.

Test Webhooks Through a Local Tunnel Safely

A webhook handler fails expensively. Your localhost endpoint has to be reachable over HTTPS through a secure tunnel, and if the handler behind it is slow, retries can trigger duplicate fulfillment, refund, or inventory actions. The tunnel gets the event to you. The handler design decides whether you process it once.

Build the handler in four steps

1. Verify the HMAC signature using the raw request body. Parse the body first and the signature won't match what Shopify signed, so verify before anything transforms the payload.
2. Record X-Shopify-Webhook-Id in durable storage. That stored ID is how you recognize a duplicate delivery and skip it.
3. Return a 2xx response right after safe receipt. Acknowledge first, work second. Shopify's delivery system uses HTTP keep-alive, so enable connection reuse on your endpoint too.
4. Process the event asynchronously with an idempotent worker. The worker should produce the same result if it runs twice, because retries mean it might.

The Shopify order webhooks documentation states that failed webhook deliveries are retried up to eight times over four hours, and persistent failures can remove the subscription. It also recommends using the webhook ID to detect duplicate deliveries. The common pitfall is doing slow API calls, database writes, or third-party requests before acknowledging. Every second spent there raises timeout and retry risk.

Local webhook test cases

Run these deliberately against your local tunnel. Don't wait for production traffic to replay a payload for you.

One caveat shapes the whole design: webhook delivery is not always guaranteed. A successful first delivery proves the happy path, not permanence. For high-value order and inventory flows, add a reconciliation job or periodic API checks that compare Shopify's state with yours and repair gaps. That's the safety net when an event never arrives at all.

Debug Local Failures Step by Step

Start from what you see: a preview that won't load, a webhook that never arrives, a checkout that behaves differently from the preview. Then work in order, because each step rules out a cheaper explanation than broken code.

1. Read the CLI output first. If your team uses JSON output, read the session status and JSONL log for the failing run before guessing.
2. Confirm the target. Check which store and which development theme or app preview the session points at. A wrong target explains most confusing results.
3. Check the tunnel. Confirm the URL is live and served over HTTPS, and restart it if it has dropped.
4. Inspect webhooks directly. Check subscription status and retry history, then compare the delivered payload with what your handler expected.
5. Reproduce small. Use the smallest payload or the single affected page before changing code, so the fix maps to one cause.
6. Verify payments separately. If checkout fails, confirm the provider is in test mode and the staging checklist ran against it.
7. Clean the environment. Run app dev clean or delete the stale development theme so the next session starts clean.

Write down each failure and its fix in a short team note. The second time a symptom appears, you should be reading an answer, not re-running the whole sequence.

Automate Checks with JSON Output and CI

The assumption worth challenging is that the CLI is something a developer sits and watches. The Shopify CLI releases describe Shopify CLI 5.0 standardizing JSON output across major command areas and adding streaming JSON for app dev, with advice to update scripts and CI workflows that consume older output contracts. Scripts can now read preview state directly instead of scraping terminal text.

The CLI also records development sessions, preview status, and JSONL logs, so a coding agent can reuse an active session and your team can retain logs for debugging. That's useful. It's also where the risk moves.

Structured output makes these automated checks practical in a pipeline.

Where each check runs

Keep fast feedback local and authoritative checks remote. That division matches the engineering pipeline insights from TekRecruiter, and it pairs with a disciplined Shopify Git integration so every automated run ties back to a branch.

Agent-friendly commands make provisioning, deployment, and deletion faster. Faster destructive actions demand branch isolation, approval gates, and an audit trail of who or what ran them.

Automation speeds up the workflow, but permissions decide whether it stays safe.

Confirm Your Dev Setup Before the Next Release

Don't ship the next change until the environment itself passes review. Four checks cover the failure points that matter most.

1. Each branch has its own development store or theme, so previews can't overwrite each other.
2. The CLI version is pinned, and the pipeline validates its JSON output against the expected schema.
3. The webhook test cases pass, including duplicate delivery and bad signature handling.
4. The release gate has a named approver, recorded with the release.

If your team doesn't have the time to keep these checks running, we can help as an official Shopify Partner Agency. Our Shopify Expertise service provides an augmented team of Shopify specialists to maintain and enhance a project, and the packages require no commitment.

Run the four checks on your current project today and note the first one that fails. That's your next fix, before any new feature work.

If your local workflow needs the environment discipline covered here, branch isolation, webhook testing, and a release gate your team can sustain, ECORN can set it up and maintain it with you. Tell us where your previews or releases keep breaking, and we'll help you turn that fragile setup into a repeatable one.