shopify-app

CRITICAL GOTCHAS (Top 10)

1. Never Use Polaris url Prop for Internal Navigation

// WRONG — breaks out of iframe
<Button url="/app/pricing">Upgrade</Button>

// CORRECT — stays in iframe
const navigate = useNavigate();
<Button onClick={() => navigate('/app/pricing')}>Upgrade</Button>

Rule: url prop is only safe for external URLs. Use useNavigate() for internal routes.

2. Never Use NODE_ENV for Billing isTest Flag

// WRONG — always false on Lambda (staging included)
isTest: process.env.NODE_ENV !== 'production'

// CORRECT — detect via Shopify API
isTest: await isDevelopmentStore(admin)

3. useFetcher Data Goes to fetcher.data, Not useActionData()

// WRONG — always undefined when using fetcher
const actionData = useActionData<typeof action>();

// CORRECT — read from fetcher
const fetcher = useFetcher();
const fetcherData = fetcher.data as { ok?: boolean; error?: string } | undefined;

4. useState Doesn't Sync with Loader After Save

// WRONG — state diverges from loader after save
const [brandColor, setBrandColor] = useState(settings.brandColor);

// CORRECT — sync from loader when data changes
const lastSyncRef = useRef(settings.updatedAt);
useEffect(() => {
  if (settings.updatedAt !== lastSyncRef.current) {
    setBrandColor(settings.brandColor);
    lastSyncRef.current = settings.updatedAt;
  }
}, [settings.updatedAt, settings.brandColor]);

5. Parent + Child Loaders Run in Parallel (Billing Race Condition)

// CORRECT — redirect after billing sync to force clean second load
const url = new URL(request.url);
if (url.searchParams.has('charge_id')) {
  url.searchParams.delete('charge_id');
  throw redirect(url.pathname + url.search);
}

6. App Proxy: GET Only, No External CSS/JS

Constraint	Detail
GET only	Proxy only forwards GET. POST must go directly to the app URL.
No external CSS/JS	<link> and <script src> resolve against storefront domain and 404.
No Tailwind ?inline	Tailwind 4's Vite plugin doesn't process @tailwind for ?inline imports.
No client-side hydration	React Router JS bundles don't load through the proxy.

7. Plus Dev Stores Can't Approve Test Charges

Create a non-Plus (Basic) dev store for billing testing. Plus dev stores show "This feature isn't currently available."

8. Custom Apps Cannot Use Billing API

App must be Public or Unlisted distribution — not Custom.

9. CloudFront Strips Host Header — CSRF Failure

// CDK fix: add x-forwarded-host custom origin header
const apiOrigin = new origins.HttpOrigin(apiDomain, {
  customHeaders: { 'x-forwarded-host': config.domainName },
});

10. shopify app dev --store Flag Ignored with Cached Association

# WRONG — --store flag is ignored
shopify app dev --store different-store.myshopify.com

# CORRECT — reset cached association first
shopify app dev --reset

---

Quick Reference

shopifyApp() Config Skeleton

const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET || '',
  apiVersion: ApiVersion.October25,
  scopes: process.env.SCOPES?.split(','),
  appUrl: process.env.SHOPIFY_APP_URL || '',
  authPathPrefix: '/auth',
  sessionStorage: new DynamoDBSessionStorage(),
  distribution: AppDistribution.AppStore,
  billing: { /* plan definitions */ },
  future: { expiringOfflineAccessTokens: true },
});

Route Naming Conventions

Pattern	Purpose	URL
app.tsx	Layout (nav, Polaris, billing)	—
app._index.tsx	Dashboard	/app
app.forms.$id.tsx	Form editor	/app/forms/:id
proxy.tsx	Public proxy layout	—
api.submit-application.tsx	POST endpoint	/api/submit-application
webhooks.app.uninstalled.tsx	Webhook handler	—

Prefixes: app. = authenticated admin, proxy. = public HMAC-verified, api. = headless, webhooks. = Shopify webhooks.

Layout Route (app.tsx) Pattern

• Loads Polaris styles, runs authenticate.admin(), syncs billing to DynamoDB
• Provides <AppProvider>, <s-app-nav>, <ClientOnly> wrapping <PolarisProvider>
• Includes ErrorBoundary and headers from boundary
• Uses shouldRevalidate to skip revalidation on POST (prevents flicker)

shouldRevalidate Pattern

export const shouldRevalidate = ({ formMethod, defaultShouldRevalidate }) => {
  if (formMethod === 'POST') return false;
  return defaultShouldRevalidate;
};

ClientOnly Component

export function ClientOnly({ children, fallback = null }: Props) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => { setMounted(true); }, []);
  return mounted ? <>{children}</> : <>{fallback}</>;
}

SSR Hydration Rule

NEVER use inline event handlers — they cause hydration mismatches in SSR apps. Always use onClick, onChange, etc. via React state and handlers.

---

Project Structure

your-app/
  app/
    routes/              # File-based routes (app.*, proxy.*, api.*, webhooks.*)
    components/          # React components (ClientOnly, etc.)
    services/            # Business logic (*.server.ts)
      dynamodb/          # keys.ts, mappers.ts
    lib/                 # Core infra (dynamodb.server.ts, config.server.ts)
    lambda-workers/      # SQS handlers (email, export)
    shopify.server.ts    # shopifyApp() config
    lambda.server.ts     # Lambda entry point
  infra/                 # CDK stacks
  tests/                 # Playwright E2E
  extensions/            # Shopify app extensions

Service Conventions

• All DB access through app/services/*.server.ts
• First param is always shopDomain (multi-tenant scoping)
• Keys via app/services/dynamodb/keys.ts
• .server.ts suffix = tree-shaken from client bundles

Key Environment Variables

Variable	Source	Description
SHOPIFY_API_KEY	Secrets Manager	App API key
SHOPIFY_API_SECRET	Secrets Manager	App API secret
SHOPIFY_APP_URL	SSM	App URL
DYNAMODB_TABLE	SSM	Table name
DYNAMODB_ENDPOINT	.env (local)	DynamoDB Local endpoint
AWS_S3_BUCKET	SSM	Documents bucket
EMAIL_QUEUE_URL	SSM	SQS email queue URL

---

Scope

In scope: Embedded Shopify apps, React Router v7, DynamoDB single-table, Lambda, SQS, CDK, Polaris, App Proxy, Billing API, Webhooks, GDPR compliance.

Out of scope: Liquid theme development, Hydrogen/headless, Checkout UI Extensions, Shopify Functions, POS extensions, Prisma/PostgreSQL.

---

Companion Tools

Use the official Shopify Dev MCP server alongside this skill for documentation search, GraphQL schema exploration, and Liquid validation. See shopify.dev/docs/apps/build/devmcp.

MCP config (add to your .claude/settings.json or Claude Desktop config):

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp"]
    }
  }
}

---

Orchestrator Pattern

When building a new feature, decompose into layers and build each before moving to the next:

0. Explore — constraints, architecture, security, integration points (references/feature-exploration.md)
1. Database — keys, entity design, queries (references/dynamodb-patterns.md)
2. API — service functions, route loader/action (references/react-router-patterns.md)
3. UI — Polaris components, state management (references/polaris-ui-patterns.md)

Step 0 runs when planning or analyzing a feature — not during active implementation. Build and test each layer independently. This prevents coupling bugs and makes code review easier.

---

When to Consult References

Task	Reference
Routing, loaders, actions, fetchers	references/react-router-patterns.md
DynamoDB keys, queries, transactions	references/dynamodb-patterns.md
GraphQL API, customers, metafields	references/shopify-api-patterns.md
Billing flow, plans, trials	references/billing-patterns.md
App Proxy pages, HMAC, forms	references/app-proxy-patterns.md
Webhook handlers, GDPR, uninstall	references/webhook-patterns.md
Lambda cold start, SQS workers	references/lambda-architecture.md
CDK stacks, CloudFront, monitoring	references/cdk-infrastructure.md
Polaris UI, design tokens, composition	references/polaris-ui-patterns.md
Email queuing, suppression, Resend	references/email-patterns.md
Multi-tenancy, CORS, S3 presigned URLs	references/security-patterns.md
Playwright, FrameLocator, selectors	references/testing-patterns.md
Docker, DynamoDB Local, startup	references/local-dev-patterns.md
Zero-to-production deployment, AWS setup, DNS, CI/CD	references/production-deployment.md
Planning a new feature, analyzing constraints	references/feature-exploration.md
File naming, service patterns, env vars, TOML	references/project-conventions.md