This is the guide I wish I had when I shipped my first app. It covers everything from creating a development store to deploying to production — including the mistakes that took me days to figure out.
Prerequisites
You'll need a Shopify Partner account (free), Node.js 20+, and basic TypeScript/React knowledge. I'm using VS Code with ESLint + Prettier — any editor works, but make sure you have TypeScript support.
Step 1: Create a Development Store
Don't use a regular Shopify trial — you need a development store tied to your Partner account. Development stores give you:
- No 3-day trial limits
- Access to all API scopes without merchant approval
- Ability to install unpublished apps
- Test billing without real credit cards
- Unlimited staff accounts for testing
How to Create One
- Log in to Partner Dashboard
- Go to Stores → Add store → Development store
- Select the Development plan (not trial)
- Fill in:
- Store name (e.g., "My Test Store")
- Store password (you'll need this to log in)
- Industry (any — doesn't matter for testing)
- Click Create store
- Note the
.myshopify.com domain — you'll need it everywhere
I've seen people spend an hour debugging OAuth only to realize they put their personal store domain in the SHOP variable instead of the development store domain. Double-check this now.
Step 2: Create Your App in Partner Dashboard
Initial Setup
- Go to Apps → Create app → Create app manually
- App name: anything descriptive (this is the internal name, not what merchants see)
- After creation, you'll land on the overview page. Note these immediately:
- API Key (Client ID)
- API Secret Key (Client Secret)
You'll need both for your .env file.
Configure App URL and Redirects
In your app settings, under Configuration → App setup:
- App URL:
https://localhost:3000 (for local development)
- Allowed redirection URL(s): Add
https://localhost:3000/auth/callback
This has to match your local server exactly. A trailing slash mismatch (/auth/callback vs /auth/callback/) will silently break OAuth — no error message, just a redirect loop. I lost an afternoon to this.
Configure API Scopes
Under Configuration → Access scopes, request only what you need:
For a discount app:
read_products, write_discounts, read_orders
For an app with storefront customization:
read_products, write_products, write_script_tags
For an app with checkout extensions:
read_products, write_checkouts
Request only what you actually need. Shopify reviews your real API calls during App Store submission — if you're requesting write_products but never calling it, your app gets rejected. Start minimal. You can add scopes later, though merchants will need to re-authorize.
Step 3: Set Up Environment Variables
Create a .env file in your project root:
# Required — from Partner Dashboard
SHOPIFY_API_KEY=your-api-key-here
SHOPIFY_API_SECRET=your-api-secret-here
SCOPES=read_products,write_discounts,read_orders
SHOP=your-dev-store.myshopify.com
# For billing (optional during development)
SHOPIFY_BILLING_ENABLED=false
# Database — PostgreSQL recommended
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
# App host (for webhooks and OAuth callbacks)
HOST=https://localhost:3000
# For production — set this to a random 32-character hex string
ACCESS_TOKEN_ENCRYPTION_KEY=
# Webhook secret (auto-generated by Shopify, but you can set it)
WEBHOOK_SECRET=
Don't commit .env to Git — add it to .gitignore right now before you forget.
Environment-Specific Files
For team development, create:
.env.example — template with placeholder values (safe to commit)
.env.local — local overrides (gitignored)
.env.production — production values (managed by your hosting platform)
Step 4: Start the Development Server
Using ShopForge Scaffold
The fastest way to get started:
git clone https://github.com/yuntongsoft/shopforge.git my-app
cd my-app
npm install
npm run dev
Your app is now running at https://localhost:3000.
Install the App on Your Dev Store
Option 1: Direct URL
Open this in your browser (replace with your dev store domain):
https://your-dev-store.myshopify.com/admin/oauth/install?client_id=YOUR_API_KEY
Option 2: Shopify CLI (Recommended)
npm run dev -- --store=your-dev-store.myshopify.com
The CLI automatically opens the install flow in your browser. Click Install app to authorize.
What Happens During Install
- Shopify redirects to your
/auth endpoint with a temporary code
- Your server exchanges the
code for an access token
- The access token is stored (encrypted) in your database
- Shopify redirects back to your app with a session token
- Your frontend includes this session token in all subsequent API calls
If you see "Example Domain" instead of your app UI after install, your App URL isn't pointing to your server. Go back to Step 2 and check the configuration.
Step 5: Understanding the Project Structure
A production Shopify app needs several pieces working together:
my-app/
├── app/
│ ├── routes/ # Remix routes (admin pages)
│ │ ├── app._index.tsx # Dashboard
│ │ ├── app.settings.tsx # Settings page
│ │ └── auth.tsx # OAuth handler
│ ├── auth/ # Session token validation
│ ├── webhooks/ # Webhook handlers
│ │ ├── app-uninstalled.ts
│ │ └── gdpr.ts
│ ├── billing/ # Subscription plan management
├── prisma/
│ └── schema.prisma # Database schema
├── extensions/ # Theme Extensions (storefront)
├── .env # Environment variables
└── shopify.app.toml # App configuration
Key Concepts
OAuth Flow:
- Access token: Long-lived, used for server-to-server API calls
- Session token: 60-second JWT, used to authenticate requests from the embedded admin UI
- You need both — session token proves the merchant is logged in; access token lets you call Shopify's API
Embedded Apps:
- Your app runs inside an iframe in the Shopify Admin
- Use Shopify App Bridge for navigation, toasts, modals
- All admin pages must use Polaris components for native look and feel
Theme Extensions:
- Optional — lets you inject UI into the storefront
- Uses App Blocks and App Embed Blocks
- Merchants must manually enable them in Theme Editor
Step 6: Register GDPR Webhooks (Required)
This part isn't optional. Shopify won't approve your app for the App Store without these three webhook handlers, and most tutorials don't mention them until you're ready to submit:
| Webhook | When It Fires | What You Must Do |
|---|---|---|
| CUSTOMERS_DATA_REQUEST | Merchant requests customer data | Return all stored data for that customer within 30 days |
| CUSTOMERS_REDACT | Customer requests data deletion | Delete all personal data for that customer |
| SHOP_REDACT | App is uninstalled + 48 hours pass | Delete all store data |
Register in Partner Dashboard
Under Configuration → Privacy compliance:
- Customer data request URL:
https://your-app.com/webhooks/gdpr/customers-data-request
- Customer data erasure URL:
https://your-app.com/webhooks/gdpr/customers-redact
- Shop data erasure URL:
https://your-app.com/webhooks/gdpr/shop-redact
Implement Handlers
// app/webhooks/gdpr.ts
import { db } from "~/lib/db";
export async function handleCustomersRedact(request: Request) {
const { customer } = await request.json();
// Delete all personal data associated with this customer
await db.customerData.deleteMany({
where: {
email: customer.email,
},
});
await db.auditLog.create({
data: {
action: "CUSTOMERS_REDACT",
email: customer.email,
timestamp: new Date(),
},
});
return new Response(null, { status: 200 });
}
export async function handleShopRedact(request: Request) {
const { shop_id, shop_domain } = await request.json();
// Delete all data for this shop
await db.store.deleteMany({
where: { domain: shop_domain },
});
return new Response(null, { status: 200 });
}
If your app ships without these handlers, it gets auto-rejected during review. You can test them locally with the Shopify CLI's webhook simulator — I'd recommend doing that before you submit.
Step 7: Add Billing (Optional but Recommended)
Shopify's Billing API lets you charge merchants a subscription fee. This is how most Shopify apps make money.
Define Plans
// shopify-config.ts
billing: {
"Free": {
interval: BillingInterval.Every30Days,
amount: 0,
currencyCode: "USD",
},
"Pro": {
interval: BillingInterval.Every30Days,
amount: 9.99,
currencyCode: "USD",
},
"Business": {
interval: BillingInterval.Every30Days,
amount: 29.99,
currencyCode: "USD",
},
}
Check Active Subscription
// In your loader or action
const billing = await shopify.billing.check({
session,
plans: ["Pro", "Business"],
isTest: true, // true for development stores
});
if (!billing.hasActivePayment) {
throw redirect("/app/pricing");
}
Create a Billing Page
// app/routes/app.pricing.tsx
import { Page, Layout, Card, Text, BlockStack, Button } from "@shopify/polaris";
import { useSubmit } from "@remix-run/react";
export default function PricingPage() {
const submit = useSubmit();
const handleSubscribe = (plan: string) => {
submit({ plan }, { method: "post", action: "/app/billing/subscribe" });
};
return (
<Page title="Pricing">
<Layout>
<Layout.Section>
<Card>
<BlockStack gap="4">
<Text variant="headingMd" as="h2">Choose your plan</Text>
<div className="grid grid-cols-2 gap-4">
<Card padding="4">
<BlockStack gap="2">
<Text variant="headingSm">Pro — $9.99/month</Text>
<Text as="p">Unlimited discounts, analytics, priority support</Text>
<Button onClick={() => handleSubscribe("Pro")}>
Subscribe
</Button>
</BlockStack>
</Card>
<Card padding="4">
<BlockStack gap="2">
<Text variant="headingSm">Business — $29.99/month</Text>
<Text as="p">Everything in Pro + custom integrations</Text>
<Button onClick={() => handleSubscribe("Business")}>
Subscribe
</Button>
</BlockStack>
</Card>
</div>
</BlockStack>
</Card>
</Layout.Section>
</Layout>
</Page>
);
}
Development stores support test billing — no real credit card needed. Set isTest: true during development. Switch to false for production.
Step 8: Build Your First Admin Page
Admin pages use Shopify's Polaris design system. Here's a complete dashboard example:
// app/routes/app._index.tsx
import type { LoaderFunctionArgs } from "@remix-run/node";
import { json } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";
import { Page, Layout, Card, Text, BlockStack, Badge } from "@shopify/polaris";
import { authenticate } from "../shopify.server";
export const loader = async ({ request }: LoaderFunctionArgs) => {
const { admin, session } = await authenticate.admin(request);
// Query shop info
const response = await admin.graphql(`
{
shop {
name
email
plan { displayName }
myshopifyDomain
}
}
`);
const data = await response.json();
// Check billing status (shopify is the instance from shopify.server.ts)
const billing = await shopify.billing.check({
session,
plans: ["Pro", "Business"],
isTest: process.env.NODE_ENV !== "production",
});
return json({
shop: data.data.shop,
hasActivePlan: billing.hasActivePayment,
});
};
export default function Dashboard() {
const { shop, hasActivePlan } = useLoaderData<typeof loader>();
return (
<Page title="Dashboard">
<Layout>
<Layout.Section>
<Card>
<BlockStack gap="3">
<div className="flex items-center justify-between">
<Text variant="headingMd" as="h2">
Welcome to {shop.name}
</Text>
<Badge tone={hasActivePlan ? "success" : "warning"}>
{hasActivePlan ? "Active Plan" : "Free Trial"}
</Badge>
</div>
<Text as="p">Domain: {shop.myshopifyDomain}</Text>
<Text as="p">Plan: {shop.plan.displayName}</Text>
<Text as="p">Contact: {shop.email}</Text>
</BlockStack>
</Card>
</Layout.Section>
<Layout.Section variant="oneThird">
<Card>
<BlockStack gap="2">
<Text variant="headingSm" as="h3">Quick Actions</Text>
<Button url="/app/settings">Settings</Button>
<Button url="/app/pricing">Upgrade Plan</Button>
</BlockStack>
</Card>
</Layout.Section>
</Layout>
</Page>
);
}
Polaris Tips
The component hierarchy matters: <Page> → <Layout> → <Layout.Section> → <Card>. Get that nesting right and everything else falls into place. Use <BlockStack> for vertical spacing — it replaced the old <Stack> component. For text, stick to semantic variants like headingMd and bodyMd rather than hardcoding font sizes.
One thing that trips people up: if your app supports multiple languages, wrap all user-facing strings with the useI18n() hook from the start. Retrofitting i18n later is painful.
Step 9: Deploy to Production
Pre-Deployment Checklist
- [ ]
HOST env var points to production URL (e.g., https://myapp.com)
- [ ] Database is provisioned and migrated (
npx prisma migrate deploy)
- [ ] All GDPR webhook URLs are set in Partner Dashboard
- [ ] App URL and redirect URLs updated to production domain
- [ ]
NODE_ENV=production
- [ ]
ACCESS_TOKEN_ENCRYPTION_KEY is set (32-char hex string)
- [ ]
WEBHOOK_SECRET is configured
- [ ]
SHOPIFY_BILLING_ENABLED=true (if using billing)
- [ ] Test billing switched to
isTest: false
Recommended Hosting
Fly.io (recommended for Shopify apps):
- Global edge network
- PostgreSQL add-on
- Easy scaling
- Free tier available
# Deploy to Fly.io
fly launch
fly deploy
Alternatives:
- Railway — simpler UI, good for small apps
- Render — generous free tier
- AWS/VPS — full control, more setup
Post-Deployment Steps
- Update App URL in Partner Dashboard to your production URL
- Update webhook URLs to production endpoints
- Test the install flow on your production app
- Monitor logs for errors (
fly logs or your hosting platform's logs)
- Set up error tracking (Sentry recommended)
Things That Will Go Wrong (and How to Fix Them)
"Example Domain" Shows Instead of Your App
Your App URL in the Partner Dashboard isn't pointing to your running server. Check three things: is the server actually running (npm run dev)? Does the App URL match exactly — including protocol and port? If you're using the CLI tunnel, those expire after about 10 minutes, so it might have died while you were coding.
OAuth Redirect Mismatch
The error message says Redirect URI does not match configured redirect URI. Nine times out of ten, this is a trailing slash. Your config says /auth/callback but the request hits /auth/callback/ (or vice versa). Check both the Partner Dashboard and your .env — they need to be character-for-character identical.
401 Errors After Deploy
The app loads fine but API calls fail. This usually means your access token went stale. Development stores can invalidate tokens when they're paused or reset. Reinstall the app to get fresh tokens, and make sure your SHOPIFY_API_KEY and SHOPIFY_API_SECRET still match what's in the Partner Dashboard.
Webhooks Returning 401
Check that WEBHOOK_SECRET is set in your .env (copy it from the Partner Dashboard). For background webhooks, you need offline access tokens — session tokens won't work there since there's no browser session. If you're still stuck, the token refresh logic in the OAuth article might help.
Billing Works in Dev but Not Production
You probably forgot to flip isTest from true to false. Also double-check that your billing plans are actually defined in shopify-config.ts and that SHOPIFY_BILLING_ENABLED=true is set in your production environment.
Where to Go from Here
The OAuth flow is the hardest part. Once it's working, everything else is incremental.
The next thing I'd look at is how session tokens and access tokens actually work under the hood — there's a race condition in token refresh that bit us hard in production, and it's worth understanding before your app has real users.
After that, it depends on what you're building:
- Selling to merchants? Add billing and start thinking about your pricing page.
- Modifying the storefront? Look into Theme Extensions (App Blocks) and Checkout Extensions.
- Building discount logic? Shopify Functions replaced the old ScriptTag approach — they're faster and run at the edge.
The ShopForge docs have the full API reference if you need it. And if you find a bug or get stuck, open an issue on GitHub — I'd rather hear about it than have you silently give up.
A Few Things I'd Do Differently
Looking back at the apps I've shipped, here's what I wish I'd known earlier:
Don't try to build everything at once. Get OAuth working. Then add billing. Then webhooks. Each of these is a rabbit hole on its own, and trying to wire them all up simultaneously is a great way to spend a weekend debugging something that isn't even broken.
Shopify's error messages are actually useful. If you see "scopes mismatch," check your scope configuration before you start rewriting your OAuth handler. I've lost hours to this.
The CLI tunnel expires. If your app suddenly stops loading during development, the tunnel probably died. Restart npm run dev and it'll create a new one. Don't try to manage tunnels manually — the CLI handles it.
Plan for App Store review from day one. GDPR webhooks, proper error handling, minimal scopes — these aren't "nice to have" features you can add later. They're hard requirements. Building them in after the fact is painful. Build them in now while the code is fresh.
Related Articles