Quick-start guide for setting up a local development environment.
| Tool | Version | Install |
|---|---|---|
| Node.js | >= 20.10.0 | nodejs.org |
| pnpm | >= 9.15.0 | corepack enable && corepack prepare pnpm@9.15.0 --activate |
| cloudflared | latest | brew install cloudflared |
| Shopify CLI | >= 3.74 | Installed via @shopify/cli dev dependency |
Before you begin, make sure you have access to the following. Ask a team lead if you need credentials.
| Account / Key | Where to get it |
|---|---|
| Supabase project (staging) | Supabase dashboard -- ask team for staging project invite |
| Shopify Partners account | partners.shopify.com |
| Shopify dev store | Created via Shopify Partners, or ask team for kernel-kings.myshopify.com access |
| Trackstar API key | Ask team lead |
| Cloudflare tunnel token | Cloudflare Zero Trust dashboard > Tunnels > swyft-io > Token |
git clone https://github.com/swyft-io/swyft.git
cd swyft
pnpm install
The staging env example lives at apps/shopify-app/.env.staging.example.
cd apps/shopify-app
cp .env.staging.example .env.staging
Open .env.staging and fill in the values marked <get from team>:
| Variable | Source |
|---|---|
CLOUDFLARE_TUNNEL_TOKEN |
Cloudflare Zero Trust dashboard (ask team) |
SUPABASE_ANON_KEY |
Supabase dashboard > Project Settings > API |
SUPABASE_SERVICE_ROLE_KEY |
Supabase dashboard > Project Settings > API (keep secret) |
TRACKSTAR_API_KEY |
Trackstar dashboard (ask team) |
SHOPIFY_API_SECRET |
Shopify Partners > Apps > Swyft Staging > Client credentials |
SHOPIFY_CLI_STOREFRONT_PASSWORD |
Shopify dev store settings (ask team) |
The following are pre-filled and should not need changes:
SUPABASE_URL, SHOPIFY_API_KEY, SHOPIFY_APP_URL, SCOPES, POSTHOG_*cp .env.staging .env
The dev script reads from .env at runtime, so this copy step is required.
From the repository root:
cd apps/shopify-app && pnpm dev:staging
Or equivalently, from the repo root:
pnpm dev:staging
This single command (dev-with-env.sh) does everything:
cloudflared installed, .env exists, tunnel token set)@swyft/database, @swyft/billing)http://localhost:3000https://shopify.swyft.io| Command | Why it is dangerous |
|---|---|
pnpm dev |
Spawns ~15 concurrent processes across all packages. Not what you want. |
shopify app dev |
Overwrites production URLs in shopify.app.toml, breaking the live app. |
shopify app dev --config shopify.app.toml |
Same problem -- uses production config. |
Always use pnpm dev:staging.
When everything is working, you should see output like:
[ok] ==========================================
[ok] Dev environment running!
[ok] Tunnel: https://shopify.swyft.io
[ok] Local: http://localhost:3000
[ok] Store: https://kernel-kings.myshopify.com/admin/apps/swyft-staging
[ok] ==========================================
Open the Store URL in your browser. You should see the Swyft app loaded inside the Shopify admin.
cloudflared is not installedbrew install cloudflared
CLOUDFLARE_TUNNEL_TOKEN is missing or placeholder in .envYou forgot to fill in the tunnel token, or you skipped the cp .env.staging .env step. Check apps/shopify-app/.env and ensure CLOUDFLARE_TUNNEL_TOKEN has a real value.
lsof -i :3000pnpm install from the repo rootrm -rf apps/shopify-app/node_modules/.vite apps/shopify-app/.react-router apps/shopify-app/buildMake sure you are NOT running shopify app dev directly. The staging script uses --config shopify.app.staging.toml automatically. If you see errors about TOML config, verify that apps/shopify-app/shopify.app.staging.toml exists.
Run pnpm typecheck from the repo root to see full output. Some packages need to be built first -- the dev script handles this, but you can manually run pnpm build if needed.
Swyft is a pnpm + Turborepo monorepo:
swyft/
apps/
shopify-app/ # React Router 7 Shopify embedded app (main UI)
worker/ # Cloudflare Worker (webhooks, background jobs)
web/ # Marketing site
packages/
database/ # Supabase types + query helpers
billing/ # Billing types and utilities
routing-engine/ # Order routing logic
forecasting/ # Demand forecasting engine
shared/ # Logging, constants, utilities
trackstar-client/ # Trackstar unified WMS/Cart API client
notifications/ # Notification templates
extensions/
cart-tracking/ # Shopify Web Pixel for cart abandonment
delivery-promise/ # Delivery promise theme extension
delivery-promise-checkout/ # Checkout delivery promise UI
For detailed architecture, see ROUTING-ARCHITECTURE.md and TECHNICAL-OVERVIEW.md.
For development standards, see DEVELOPMENT.md.