Documentation

Everything you need to build production-ready Shopify apps with ShopForge.

$ npx create-shopforge-app@latest

Introduction

ShopForge is an open-source Shopify app scaffold that eliminates weeks of boilerplate setup. It provides a production-ready foundation with OAuth, Billing, GDPR compliance, and more — all pre-configured and battle-tested.

Built with Next.js 14, Shopify CLI, Prisma, and Polaris, ShopForge follows Shopify's official recommendations and passes App Store review requirements out of the box.

OAuth 2.0

Automatic HMAC verification, session management, and token refresh.

Billing API

Free/Pro/Business tiers with trial support and webhook handling.

GDPR Ready

Mandatory customer data request/redaction webhooks pre-implemented.

Prisma ORM

Type-safe database queries with PostgreSQL and automatic migrations.

Installation

Get your development environment ready in under 5 minutes.

Create a new project

bash

npx create-shopforge-app@latest my-shopify-app

Install dependencies

bash

cd my-shopify-app
npm install

Configure environment

env

# .env
SHOPIFY_API_KEY=your-api-key
SHOPIFY_API_SECRET=your-api-secret
SCOPES=read_products,write_orders,read_orders
DATABASE_URL=postgresql://user:password@localhost:5432/myapp

Start development server

bash

npm run dev

Your app will be available at https://localhost:3000 with an automatic tunnel for Shopify webhook testing.

Project Structure

Understanding the scaffold layout.

text

my-shopify-app/
├── app/
│   ├── routes/          # Remix routes (pages & API)
│   ├── services/        # Business logic layer
│   ├── components/      # Shared UI components
│   ├── shopify.server.ts  # Shopify SDK config
│   └── db.server.ts     # Prisma client
├── extensions/          # Theme & checkout extensions
├── prisma/
│   └── schema.prisma    # Database schema
├── shopify.app.toml     # App configuration
└── package.json

app/routes/ — File-based routing. Each file becomes a page or API endpoint.

app/services/ — Business logic separated from route handlers. Easy to test and reuse.

extensions/ — Shopify Functions and Theme Extensions live here.

Authentication

OAuth 2.0 flow and session management.

ShopForge handles the complete OAuth 2.0 flow automatically. When a merchant installs your app, Shopify redirects them through the OAuth process. The scaffold verifies HMAC signatures, exchanges the authorization code for an access token, and stores the session in your database via Prisma.

The key file is app/shopify.server.ts — it configures the Shopify SDK with your API credentials, scopes, and webhook handlers.

typescript

// app/shopify.server.ts
import { ApiVersion, LogSeverity } from "@shopify/shopify-api";
import "@shopify/shopify-app-remix/server";
import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
import prisma from "./db.server";

const shopify = shopifyAppRemix({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  apiVersion: ApiVersion.July25,
  scopes: process.env.SCOPES?.split(",") ?? ["read_products"],
  appUrl: process.env.SHOPIFY_APP_URL!,
  isEmbeddedApp: true,
  sessionStorage: new PrismaSessionStorage(prisma),
  logger: { level: LogSeverity.Info },
});

export default shopify;

Database (Prisma)

Type-safe queries with PostgreSQL.

ShopForge uses Prisma ORM for database operations. The schema is defined in prisma/schema.prisma and includes the Session model required by Shopify, plus your business models.

prisma

// prisma/schema.prisma
model Session {
  id            String    @id
  shop          String
  state         String
  isOnline      Boolean   @default(false)
  scope         String?
  expires       DateTime?
  accessToken   String
  userId        BigInt?
}

model Shop {
  id        String   @id @default(cuid())
  domain    String   @unique
  plan      String   @default("free")
  createdAt DateTime @default(now())
}

bash

# Run migrations
npx prisma migrate dev --name init

# Open Prisma Studio (visual DB browser)
npx prisma studio

Billing API

Monetize your app with subscription plans.

The Billing API lets you charge merchants through their regular Shopify invoice — no credit card handling, no PCI compliance. ShopForge supports Free, Pro, and Business tiers with configurable trial periods.

Define your plans in app/services/billing.server.ts and check subscription status on every admin page load.

typescript

// Create a subscription
const response = await shopify.graphql(client, `
  mutation {
    appSubscriptionCreate(
      name: "Pro Plan"
      returnUrl: ${APP_URL}/pricing
      test: true
      lineItems: [{
        plan: {
          appRecurringPricingDetails: {
            price: { amount: 9.99, currencyCode: USD }
          }
        }
      }]
    ) {
      confirmationUrl
      appSubscription { id }
    }
  }
`);

Webhooks

Real-time event handling.

Shopify sends webhooks when events occur in a merchant's store. ShopForge pre-configures all mandatory GDPR webhooks and provides a clean registration pattern for business events.

typescript

// Register webhooks in shopify.server.ts
webhooks: {
  APP_UNINSTALLED: { deliveryMethod: DeliveryMethod.Http, callbackUrl: "/webhooks" },
  CUSTOMERS_DATA_REQUEST: { deliveryMethod: DeliveryMethod.Http, callbackUrl: "/webhooks" },
  CUSTOMERS_REDACT: { deliveryMethod: DeliveryMethod.Http, callbackUrl: "/webhooks" },
  SHOP_REDACT: { deliveryMethod: DeliveryMethod.Http, callbackUrl: "/webhooks" },
  ORDERS_CREATE: { deliveryMethod: DeliveryMethod.Http, callbackUrl: "/webhooks" },
}

Shopify Functions

Custom checkout logic with WASM.

Shopify Functions run as small WASM modules on Shopify's edge infrastructure. They execute in under 10ms and can customize discounts, payment methods, delivery options, and order routing.

Generate a new function with the CLI:

bash

npm run shopify app generate extension
# Choose: function → discount / payment-customization / delivery-customization

Theme Extensions

Embed your app in the storefront.

Theme Extensions let your app render blocks in the merchant's theme — product pages, cart, checkout. They're configured via the Theme Editor, so merchants can customize placement without touching code.

Extensions live in the extensions/ directory. Each extension has its own shopify.extension.toml configuration.

Deployment

Ship to production.

ShopForge supports multiple deployment targets. The recommended approach is to use a Node.js server with PM2 for process management, behind Nginx as a reverse proxy with SSL.

bash

# Build for production
npm run build

# Start with PM2
pm2 start ecosystem.config.cjs

# Or use Docker
docker build -t my-shopify-app .
docker run -p 3000:3000 my-shopify-app

Deployment checklist:

NODE_ENV=production
SHOPIFY_APP_URL
Whitelist your domain in Shopify Partner Dashboard
npx prisma migrate deploy
test: false

API Reference