Skip to main content

CLAUDE.md Template for Shopify Development

The CLAUDE.md file is the foundation of effective Claude Code usage. It provides persistent context that Claude Code reads at the start of every session, eliminating the need to repeat project details in every prompt. This guide provides a complete, battle-tested template for Shopify development projects.

Why CLAUDE.md Matters​

Without a CLAUDE.md file, every Claude Code session starts from zero. Claude Code must discover your project structure, figure out which Shopify API version you're using, learn your coding conventions, and understand your app architecture -- all from reading files and asking questions.

With a well-written CLAUDE.md, Claude Code starts every session as a fully briefed team member who knows:

  • Your exact Shopify configuration (API version, scopes, app type)
  • Your coding standards and architectural decisions
  • How to run, test, and deploy the project
  • What mistakes to avoid
The 5-Minute Investment

Writing a good CLAUDE.md takes about 5 minutes. It saves you from repeating context in every session, which over a week of development easily saves hours of prompt engineering. It is the highest-leverage thing you can do for your Claude Code workflow.

The Complete Template​

Copy this template, customize the bracketed sections for your project, and save it as CLAUDE.md in your project root.

CLAUDE.md
# [Project Name]

## Overview
[One paragraph describing what this project does, who it's for, and its current status.]

Example: Remix-based Shopify app that enables merchants to create and manage
product bundles with automatic discount application. Currently in production
serving 200+ stores.

## Tech Stack
- **Framework**: Remix (Shopify app template)
- **Language**: TypeScript (strict mode)
- **Database**: Prisma ORM with PostgreSQL
- **UI**: Shopify Polaris v13 React components
- **Auth**: Shopify managed installation (app proxy + session tokens)
- **Testing**: Vitest (unit), Playwright (e2e)
- **Package Manager**: npm
- **Node Version**: 20 LTS

## Shopify Configuration
- **API Version**: 2025-01 (DO NOT use unstable or older versions)
- **App Type**: Embedded app (App Bridge 4)
- **Access Mode**: Online + Offline access tokens
- **Required Scopes**: read_products, write_products, read_orders, write_orders,
  read_inventory, write_inventory, read_customers
- **Webhooks**: ORDERS_CREATE, PRODUCTS_UPDATE, APP_UNINSTALLED
- **Extensions**: Theme app extension (product-bundle-block), Checkout UI extension

## Project Structure

app/ routes/ # Remix routes (app..tsx = authenticated app pages) graphql/ # GraphQL query and mutation strings queries/ # Read operations mutations/ # Write operations models/ # Prisma model helpers (.server.ts) components/ # Shared React components (Polaris-based) utils/ # Utility functions webhooks/ # Webhook handlers jobs/ # Background job processors extensions/ product-bundle/ # Theme app extension checkout-upsell/ # Checkout UI extension prisma/ schema.prisma # Database schema migrations/ # Migration files tests/ unit/ # Vitest unit tests e2e/ # Playwright e2e tests fixtures/ # Test data and mocks


## Commands
```bash
# Development
npm run dev              # Start Remix dev server
shopify app dev          # Start with Shopify CLI (ngrok tunnel + auth)
npm run dev:extensions   # Develop extensions locally

# Database
npx prisma db push       # Apply schema changes (development)
npx prisma migrate dev   # Create and apply migration
npx prisma studio        # Open database GUI

# Testing
npm test                 # Run all Vitest tests
npm test -- --watch      # Watch mode
npm run test:e2e         # Run Playwright tests
npm run test:coverage    # Generate coverage report

# Build & Deploy
npm run build            # Production build
shopify app deploy       # Deploy to Shopify
npm run lint             # ESLint check
npm run typecheck        # TypeScript type checking

Coding Standards​

TypeScript​

  • Strict mode enabled, no any types (use unknown and narrow)
  • Prefer interface over type for object shapes
  • All functions must have explicit return types
  • Use barrel exports (index.ts) for directories

React / Polaris​

  • Use Polaris components exclusively for UI -- no custom CSS for standard patterns (buttons, forms, cards, modals, data tables)
  • Follow Polaris design patterns: Page > Layout > Card hierarchy
  • Use useAppBridge() for App Bridge interactions
  • Toast for success messages, Banner for persistent info/errors
  • Loading states: use Polaris SkeletonPage/SkeletonBodyText

GraphQL​

  • All queries go in app/graphql/queries/ as exported template literals
  • All mutations go in app/graphql/mutations/
  • Always include userErrors { field message } in mutations
  • Use cursor-based pagination (never offset-based)
  • Prefix query names with operation: GetProducts, CreateBundle
  • Always specify the exact fields needed (no over-fetching)

Remix Patterns​

  • Loaders return json() responses with typed data
  • Actions handle form submissions with proper validation
  • Use authenticate.admin(request) at the start of every loader/action
  • Redirect to /auth/login on authentication failures
  • Use defer() for non-critical data that can stream

Database​

  • All database operations in *.server.ts files (never in components)
  • Use Prisma transactions for multi-table operations
  • Always include shopDomain in queries (multi-tenant isolation)
  • Soft delete with deletedAt timestamp (never hard delete)

Webhooks​

  • Verify HMAC on all webhook endpoints
  • Respond within 1 second (offload heavy work to background jobs)
  • Implement idempotency using webhook ID tracking
  • Log webhook receipt with shop domain, topic, and webhook ID

Error Handling​

  • Never swallow errors silently -- always log with context
  • Use Remix CatchBoundary/ErrorBoundary for route-level errors
  • GraphQL errors: check userErrors array first, then network errors
  • External API calls: retry with exponential backoff (max 3 attempts)

Shopify-Specific Rules​

API Usage​

  • ALWAYS use API version 2025-01
  • Use the authenticated admin client from authenticate.admin(request)
  • Never hardcode shop domains or access tokens
  • Rate limiting: track GraphQL cost points, throttle at 80% capacity
  • Use bulk operations for large data sets (1000+ items)

Polaris Guidelines​

  • Follow the Shopify App Design Guidelines for UX patterns
  • Use the AppProvider at the app root with i18n configuration
  • Navigation via Polaris NavMenu component
  • Forms use Polaris FormLayout with inline validation
  • Tables use IndexTable with bulk actions

App Bridge 4​

  • Do NOT use createApp() (that's App Bridge 3)
  • Session tokens are available via the Remix authenticate helper
  • Navigation: use standard links, App Bridge handles framing
  • Resource pickers: use the app bridge resource picker API
  • Title bar: set via Remix route meta or ui.title-bar component

Theme Extensions​

  • App blocks must be self-contained (own CSS/JS, no global pollution)
  • Use CSS custom properties for theme-aware colors
  • Liquid: always null-check objects before accessing properties
  • Schema settings must have sensible defaults
  • Test with multiple themes (Dawn, Refresh, and one vintage theme)

Testing Requirements​

  • All new features must have unit tests
  • Critical paths (checkout, payments, inventory) need e2e tests
  • Minimum 80% code coverage on models and utils
  • Mock the Shopify admin client in tests (never call real API)
  • Test webhooks with sample payloads from tests/fixtures/webhooks/
  • Run npm test before committing (pre-commit hook enforces this)

Deployment Checklist​

  1. All tests pass (npm test && npm run test:e2e)
  2. TypeScript compiles without errors (npm run typecheck)
  3. Lint passes (npm run lint)
  4. Database migrations are committed
  5. Environment variables are set in production
  6. Webhook URLs are registered for production domain
  7. Extensions are deployed (shopify app deploy)
  8. App review checklist completed (if submitting to app store)

Environment Variables​

  • SHOPIFY_API_KEY - App API key (from Partner Dashboard)
  • SHOPIFY_API_SECRET - App secret key
  • DATABASE_URL - PostgreSQL connection string
  • REDIS_URL - Redis connection for background jobs
  • SENTRY_DSN - Error tracking (optional)

DO NOT commit .env files. Use .env.example as a template.

Known Issues​

  • [List any active bugs, workarounds, or tech debt items]
  • Bulk operations occasionally timeout for shops with 50k+ products; current workaround is to chunk into batches of 10k
  • The checkout extension doesn't render in Safari < 16 due to a known Shopify bug (tracked in their issue tracker)

Architecture Decisions​

  • We use offline access tokens for background jobs and online tokens for interactive sessions
  • Bundle pricing is calculated server-side and applied via Shopify Functions (not manual discount codes) for checkout integrity
  • Customer data is NOT stored locally; always fetch fresh from Shopify to maintain compliance with data protection requirements

## Template Variations

### Theme-Only Projects

If you're working on a Shopify theme (not an app), use this simplified version:

```markdown title="CLAUDE.md for Theme Projects"
# [Theme Name]

## Overview
Custom Shopify theme based on Dawn 13.0 for [store name].
Online Store 2.0 compatible with full section-everywhere support.

## Tech Stack
- **Base Theme**: Dawn 13.0
- **Liquid**: Shopify Liquid (OS 2.0)
- **CSS**: Vanilla CSS with custom properties (no preprocessor)
- **JavaScript**: Vanilla ES6+ (no jQuery, no build step)
- **Icons**: Inline SVG from a central snippet

## Structure

assets/ # CSS, JS, and static files config/ # settings_schema.json and settings_data.json layout/ # theme.liquid and password.liquid locales/ # Translation files sections/ # All sections (reusable across templates) snippets/ # Reusable Liquid snippets templates/ # JSON templates (OS 2.0) customers/ # Account page templates


## Commands
```bash
shopify theme dev --store=mystore    # Local development
shopify theme push                    # Push to theme
shopify theme pull                    # Pull remote changes
shopify theme check                   # Run Theme Check linter

Coding Standards​

  • Sections must have complete schemas with sensible defaults
  • Always null-check Liquid objects: {% if product.metafields.custom.x %}
  • Use loading="lazy" on all images below the fold
  • CSS: mobile-first, use custom properties for colors/spacing
  • JavaScript: no global scope pollution, use IIFE or modules
  • Accessibility: all interactive elements must be keyboard navigable
  • Performance: no render-blocking JS, minimize Liquid loops

Shopify-Specific Rules​

  • Use {{ image | image_url: width: 800 }} (not img_url filter)
  • Preload critical images with fetchpriority="high"
  • Use {% render 'snippet' %} (not include)
  • Section schema: always include "class" for wrapper styling
  • Test with Theme Check: shopify theme check --fail-level error

Known Issues​

  • [List theme-specific bugs or browser compatibility notes]

### Hydrogen / Headless Projects

```markdown title="CLAUDE.md for Hydrogen Projects"
# [Project Name] - Hydrogen Storefront

## Overview
Headless Shopify storefront built with Hydrogen 2024.10 and Remix.

## Tech Stack
- **Framework**: Hydrogen (Remix-based)
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **API**: Shopify Storefront API (2025-01)
- **Hosting**: Oxygen (Shopify's edge hosting)
- **Cache**: Hydrogen's built-in caching strategies

## Shopify Configuration
- **API Version**: 2025-01 (Storefront API)
- **Storefront Access Token**: In environment variables
- **Customer Account API**: Enabled for account features

## Key Patterns
- Use Hydrogen's `<Await>` for deferred data loading
- Cache strategies: CacheLong for collections, CacheShort for cart
- SEO: Use Hydrogen's `getSeoMeta()` helper for all routes
- Analytics: Use Hydrogen's built-in Shopify analytics
- Use `<Money>` and `<Image>` components from @shopify/hydrogen

How Claude Code Uses CLAUDE.md​

Understanding how Claude Code processes CLAUDE.md helps you write better ones:

  1. Read on session start: Claude Code reads CLAUDE.md before your first prompt
  2. Always in context: The content stays in the context window for the entire session
  3. Hierarchical merge: Global (~/.claude/CLAUDE.md) + project root + subdirectory files are merged
  4. Token cost: CLAUDE.md consumes context tokens, so be concise. A 500-word CLAUDE.md is approximately 700 tokens -- a small fraction of the context window
Keep It Concise

A CLAUDE.md that's too long wastes context tokens on every single interaction. Aim for 300-800 words. Put detailed documentation in separate docs -- CLAUDE.md should be a quick reference, not a novel. Every word should earn its place.

Best Practices Checklist​

Use this checklist when writing or reviewing your CLAUDE.md:

  • API version is specified (single most important line)
  • Tech stack is listed (framework, language, database, UI)
  • All dev commands are documented (dev, test, build, deploy)
  • File structure is outlined (key directories and their purposes)
  • Coding standards are explicit (not vague "write clean code")
  • Shopify-specific rules are stated (scopes, app type, extensions)
  • Testing expectations are clear (what to test, how to run tests)
  • Known issues are documented (prevents Claude Code from hitting the same walls)
  • Environment variables are listed (without actual values)
  • No sensitive data (no API keys, tokens, or passwords)
Never Put Secrets in CLAUDE.md

CLAUDE.md is a regular file that gets committed to version control. Never include API keys, access tokens, database passwords, or any sensitive credentials. List the variable names (e.g., SHOPIFY_API_KEY) but not their values.

Evolving Your CLAUDE.md​

Your CLAUDE.md should evolve with your project. Update it when:

  • You upgrade the Shopify API version
  • You add new extensions or webhooks
  • You change architectural patterns
  • You discover new "gotchas" that waste time
  • You add or change development commands
  • Team coding standards evolve

A stale CLAUDE.md is worse than no CLAUDE.md, because it gives Claude Code confidently wrong context. Keep it current, keep it concise, and keep it honest about your project's actual state.

Next Steps​

With your CLAUDE.md in place, you're ready to explore MCP Fundamentals and learn how the Model Context Protocol can extend Claude Code's capabilities even further for Shopify development.