Documentation

GitHub

Introduction

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

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

Session Token Auth

Dual authentication: SDK admin auth + custom Session Token verification with Token Exchange.

Billing API

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

GDPR Ready

Mandatory customer data request/redaction webhooks pre-implemented.

Prisma ORM

Type-safe queries with PostgreSQL, MySQL, or SQLite. Automatic migrations.

Installation

From zero to running app in 10 minutes. Just 3 commands.

Step 1: Clone & Install

bash
git clone https://github.com/yuntongsoft/shopforge.git my-shopify-app && cd my-shopify-app && npm install

Step 2: Start the App

bash
npm run dev

The first run auto-detects missing configuration and launches an interactive setup wizard. Follow the prompts to configure your database, paste Shopify credentials, and initialize the database — all automatically.

What the setup wizard handles automatically:

No manual .env editing, no cp .env.example, no prisma db push needed.

  • SQLite database (zero config) or choose PostgreSQL/MySQL
  • Generate ENCRYPTION_KEY and CSRF_SECRET
  • Create database tables via prisma db push
  • Write .env with your Shopify API Key and Secret

Step 3: Open in Browser

While the dev server is running, press P in the terminal to open the app in your browser via Shopify dev preview.

Project Structure

Understanding the scaffold layout.

text
my-shopify-app/
├── app/
│   ├── routes/          # Remix routes (pages & API)
│   ├── services/        # Business logic (billing, email, webhook, shopify API)
│   ├── components/      # Shared UI components
│   ├── utils/           # Auth, encryption, CSRF, rate-limiter, i18n, logger
│   ├── demo/            # Demo code — one command to remove (npm run clean:demo)
│   ├── locales/         # i18n translation files (en/zh)
│   ├── shopify.server.ts  # Shopify SDK config
│   └── db.server.ts     # Prisma client
├── tests/               # All tests (utils, services, demo)
├── extensions/          # Shopify Functions (generated by npm run functions:setup)
├── templates/           # Function templates (Rust)
├── scripts/             # Build, code generator, dev tools
├── 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.

app/utils/ — Encryption, CSRF, rate limiting, auth, i18n, structured logging.

app/demo/ — Demo code isolated for easy removal. Run npm run clean:demo to strip all examples.

extensions/ — Shopify Functions and Theme Extensions live here.

Authentication

Session Token verification and Token Exchange.

ShopForge uses a dual authentication architecture. For API calls to Shopify, the SDK's authenticate.admin() provides full session management. For page loaders/actions, a custom authenticatePage() verifies Session Tokens (JWT) and exchanges them for offline access tokens via Token Exchange — no redirect needed. Both paths share encrypted token storage via Prisma.

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

typescript
// app/shopify.server.ts
import { shopifyApp, DeliveryMethod } from "@shopify/shopify-app-remix/server";
import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
import prisma from "./db.server";
import { webhookRegistry } from "~/services/webhook-registry";

const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  apiVersion: "2026-07",
  scopes: process.env.SHOPIFY_SCOPES?.split(",") ?? ["read_products", "write_products"],
  appUrl: process.env.APP_URL || "http://localhost:3000",
  isEmbeddedApp: true,
  sessionStorage: new PrismaSessionStorage(prisma),
  // Webhooks auto-generated from webhookRegistry — one-line registration
  webhooks: buildWebhookConfig(),
  hooks: {
    afterAuth: async ({ session }) => {
      await registerShop(session.shop, session.accessToken, session.scope);
    },
  },
});

export default shopify;
export const { authenticate } = shopify;

Database (Prisma)

Type-safe queries with PostgreSQL, MySQL, or SQLite.

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. Switch databases anytime via npm run setup.

prisma
// prisma/schema.prisma
model Shop {
  id             String   @id @default(uuid())
  shopifyDomain  String   @unique @map("shopify_domain")
  shopifyToken   String   @map("shopify_token")  // AES-256-GCM encrypted
  plan           String   @default("free")
  locale         String   @default("en")
  isDeleted      Boolean  @default(false)
  createdAt      DateTime @default(now())
  updatedAt      DateTime @updatedAt
  @@map("shops")
}

model Session {
  id           String    @id
  shop         String
  accessToken  String    @map("access_token")
  isOnline     Boolean   @default(false)
  refreshToken String?   @map("refresh_token")
  expires      DateTime?
  // ... full model has 16 fields for complete OAuth lifecycle
  @@map("sessions")
}
bash
# Dev: instant schema sync
npm run db:push

# Prod: run pending migrations
npm run db:migrate

# Create a new migration
npm run db:migrate:create --name add_my_model

# Seed with demo data
npm run db:seed

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.service.ts and check subscription status on every admin page load.

typescript
// billingService handles all subscription logic
import { billingService } from "~/services/billing.service";

// Create a subscription — returns confirmation URL
const result = await billingService.createSubscription(
  "example.myshopify.com",
  "pro",           // plan: 'pro' | 'business'
  accessToken
);

if ("confirmationUrl" in result) {
  return redirect(result.confirmationUrl);
}

// Check current plan
const plan = await billingService.getShopPlan(shopId);
// "free" | "pro" | "business"

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
// One-line registration — webhooks auto-configured!
import { webhookRegistry } from "~/services/webhook-registry";

webhookRegistry.on("ORDERS_CREATE", async (shop, payload) => {
  console.log(`New order in ${shop}`);
});

// Built-in handlers (pre-registered):
// APP_UNINSTALLED     → soft-delete shop data
// APP_SUBSCRIPTIONS_UPDATE → billing lifecycle
// CUSTOMERS_REDACT    → GDPR compliance
// SHOP_REDACT         → GDPR hard delete

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.

Copy Function templates to extensions/ and configure:

bash
# Copy Function templates to extensions/ and configure
npm run functions:setup

# Edit your function logic in extensions/<name>/src/lib.rs

# Deploy to Shopify
npx shopify app deploy

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