Shopify App Boilerplate

A modern Shopify app boilerplate built with TanStack Start and TypeScript.

One Click Deploy to Railway

Architecture Overview

Frontend Stack

• TanStack Router - Type-safe routing with data loaders
• TanStack Start - Full-stack React framework
• React 19 - Latest React with concurrent features
• Shopify App Bridge - Native Shopify admin integration
• App Bridge UI - Pre-built UI components (s-* elements) using Polaris web components

Backend Stack

• Drizzle ORM - Type-safe database operations with migrations
• PostgreSQL 18.4 - Primary database
• LogTape - Structured, redacted NDJSON logging

Shopify Integration

• Admin API 2026-07 - Latest GraphQL API with generated types
• App Proxy Authentication - Secure frontend-backend communication
• Webhook Authentication - HMAC-validated webhook endpoint processing

Features

• OAuth Authentication - Secure Shopify app installation
• Session Management - Persistent sessions with database storage
• GraphQL Integration - Type-safe Shopify Admin API queries
• App Proxy Support - Authenticated frontend API calls
• Webhook Handlers - Direct HMAC-validated endpoint processing
• Request Logging - One context-rich canonical event per request
• Theme Extensions - Extensible theme app extensions

Logging

Server logs use LogTape and emit one structured http_request event when each request completes. The event accumulates request and response details, timing, security signals, Shopify authentication, app proxy and webhook context, shop plan and currency, and deployment metadata.

Shopify SDK messages enrich the active request event. Messages outside a request are emitted as standalone shopify_sdk events. Common sensitive fields such as secrets, tokens, passwords, and email addresses are recursively removed before output.

Deployment context is detected automatically from common COMMIT_SHA, Railway, Vercel, SERVICE_VERSION, REGION, INSTANCE_ID, and HOSTNAME environment variables.

Installation

1. Clone and Install Dependencies

git clone https://github.com/djordje-st/tanstack-start-shopify-app-boilerplate.git
cd tanstack-start-shopify-app-boilerplate
pnpm install

2. Start Local Services

pnpm docker:up

This starts a PostgreSQL container for local development.

3. Environment Configuration

Create a .env file with the following variables:

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/shopify_tanstack_dev

# Shopify App Credentials (from Partner Dashboard)
VITE_SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret

4. Database Setup

# Push schema to database
pnpm db:push

# Or use migrations
pnpm db:generate && pnpm db:migrate

5. Link Your Shopify App

shopify app config link

This creates/links a Shopify app and generates the shopify.app.toml configuration.

6. Start Development Server

# Start with Shopify CLI (recommended)
pnpm dev

Available Scripts

Script	Description
pnpm dev	Start dev server with Shopify CLI
pnpm app:dev	Start Vite dev server only
pnpm app:build	Build for production
pnpm app:start	Start production server
pnpm db:push	Push schema changes to database
pnpm db:generate	Generate migration files
pnpm db:migrate	Run migrations
pnpm db:studio	Open Drizzle Studio
pnpm docker:up	Start Docker services
pnpm docker:down	Stop Docker services
pnpm docker:destroy	Remove Docker volumes
pnpm graphql:generate	Generate GraphQL types
pnpm typecheck	Run TypeScript checks
pnpm lint	Run ESLint
pnpm format	Format with Prettier

Project Structure

src/
├── components/          # React components
├── db/
│   ├── migrations/      # Drizzle migrations
│   └── schema/          # Database schema (modular)
├── graphql/             # GraphQL queries
├── routes/              # TanStack Router routes
│   └── api/             # API routes (webhooks, proxy)
├── types/               # TypeScript definitions
│   └── generated/       # Auto-generated types
└── utils/
    ├── middleware/      # Request middleware
    └── shopify/         # Shopify utilities

Troubleshooting

App won't load in Shopify admin

• Run shopify app config link to ensure app is properly linked
• Check that your tunnel URL matches the app configuration
• Ensure App Bridge scripts are loading correctly

Database connection failed

• Run pnpm docker:up to start PostgreSQL
• Verify DATABASE_URL format: postgresql://user:password@host:port/database
• Run pnpm db:push to ensure schema is up to date

GraphQL queries failing

• Verify app has correct scopes in shopify.app.toml
• Check that access token is valid
• Run pnpm graphql:generate to regenerate types

Resources

• Shopify App Development
• TanStack Router Documentation
• TanStack Start Documentation
• Drizzle ORM Documentation
• Shopify CLI Documentation
• App Bridge UI Components

Contributing

Contributions are welcome:

• Report issues and bugs
• Suggest improvements
• Submit pull requests