Documentation
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
git clone https://github.com/yuntongsoft/shopforge.git my-shopify-app && cd my-shopify-app && npm installStep 2: Start the App
npm run devThe 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.
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.jsonapp/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.
// 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/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")
}# 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:seedBilling 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.
// 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.
// 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 deleteShopify 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:
# 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 deployTheme 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.
# 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-appDeployment checklist:
NODE_ENV=productionSHOPIFY_APP_URL- Whitelist your domain in Shopify Partner Dashboard
npx prisma migrate deploytest: false