create-shopify-firebase-app 1.0.0 → 1.1.0

package/README.md

@@ -11,10 +11,9 @@ npx create-shopify-firebase-app my-app
 ```
 
 <p align="center">
-  <img src="https://img.shields.io/badge/Shopify-App-7AB55C?logo=shopify&logoColor=white" />
-  <img src="https://img.shields.io/badge/Firebase-Backend-FFCA28?logo=firebase&logoColor=black" />
+  <img src="https://img.shields.io/badge/Shopify-2026--01-7AB55C?logo=shopify&logoColor=white" />
+  <img src="https://img.shields.io/badge/Firebase-v2%20Functions-FFCA28?logo=firebase&logoColor=black" />
   <img src="https://img.shields.io/badge/TypeScript-Functions-3178C6?logo=typescript&logoColor=white" />
-  <img src="https://img.shields.io/badge/Express-Server-000000?logo=express&logoColor=white" />
 </p>
 
 ---
@@ -23,12 +22,13 @@ npx create-shopify-firebase-app my-app
 
 The **Firebase alternative** to `shopify app init`. Instead of Remix + Prisma + Vercel, you get:
 
-- **Firebase Cloud Functions** (Express + TypeScript) for your backend
+- **Firebase v2 Cloud Functions** (gen 2) — 4 independent, auto-scaling TypeScript functions
 - **Cloud Firestore** for sessions and app data (auto-scaling, free tier)
 - **Firebase Hosting** for your embedded admin dashboard (free)
 - **Vanilla HTML/JS + App Bridge** for the frontend (no React, no build step)
 - **Theme App Extension** for storefront UI (works on all Shopify plans)
-- **Production-ready** OAuth, session tokens, webhooks, GDPR handlers — all included
+- **Shopify API 2026-01** (latest) — OAuth, session tokens, webhooks, GDPR handlers
+- **Production-ready** — deploy with one command, scale to millions
 
 One `npx` command scaffolds everything, installs dependencies, wires up Firebase, and initializes git. You're ready to `firebase deploy`.
 
@@ -121,7 +121,7 @@ shopify app dev
 
 | | `shopify app init` (Remix) | `create-shopify-firebase-app` |
 |---|---|---|
-| **Backend** | Remix server | Firebase Cloud Functions (Express) |
+| **Backend** | Remix server (monolith) | Firebase v2 Cloud Functions (4 independent functions) |
 | **Database** | Prisma + PostgreSQL | Cloud Firestore (NoSQL, auto-scaling) |
 | **Frontend** | React + Polaris | Vanilla HTML/JS + App Bridge |
 | **Hosting** | Vercel / Fly.io / Heroku | Firebase Hosting (free tier) |
@@ -130,7 +130,7 @@ shopify app dev
 | **Deploy** | Varies | `firebase deploy` (one command) |
 | **Cost** | $5-25/month hosting | Free tier covers most apps |
 | **Framework knowledge** | Remix + React required | Express + HTML (that's it) |
-| **Backend code** | ~2000+ lines (framework) | ~350 lines (you own all of it) |
+| **Scaling** | Single server | Per-function auto-scaling (Cloud Run) |
 | **GDPR webhooks** | Auto-handled | Included (ready for App Store) |
 | **Theme extensions** | Supported | Supported (same Shopify format) |
 | **Shopify Functions** | Supported | Supported (add via Shopify CLI) |
@@ -155,18 +155,18 @@ shopify app dev
 
 ```
 my-app/
-├── shopify.app.toml              # Shopify app config
+├── shopify.app.toml              # Shopify app config (API 2026-01)
 ├── firebase.json                 # Firebase Hosting + Functions + Firestore
 ├── firestore.rules               # Security rules (blocks direct client access)
 │
-├── functions/                    # ── Backend ──
+├── functions/                    # ── Backend (4 Cloud Functions) ──
 │   ├── src/
-│   │   ├── index.ts              # Express app + Cloud Function export
-│   │   ├── auth.ts               # OAuth 2.0 (install + callback + token storage)
+│   │   ├── index.ts              # Function exports (auth, api, webhooks, proxy)
+│   │   ├── auth.ts               # OAuth 2.0 (standalone — no Express)
 │   │   ├── verify-token.ts       # App Bridge JWT session token middleware
-│   │   ├── admin-api.ts          # Your admin dashboard API routes
-│   │   ├── proxy.ts              # Storefront-facing App Proxy routes
-│   │   ├── webhooks.ts           # Webhook handlers (uninstall + GDPR)
+│   │   ├── admin-api.ts          # Admin dashboard API routes (Express)
+│   │   ├── proxy.ts              # Storefront App Proxy routes (Express)
+│   │   ├── webhooks.ts           # Webhook handlers (standalone — no Express)
 │   │   ├── firebase.ts           # Firebase Admin SDK init
 │   │   └── config.ts             # Environment config
 │   └── .env                      # Your secrets (auto-generated, git-ignored)
@@ -187,6 +187,8 @@ my-app/
 
 ## Architecture
 
+Each function scales independently on Cloud Run (Firebase v2 / gen 2):
+
 ```
   Shopify Admin (iframe)
   ┌─────────────────────────────────────┐
@@ -195,12 +197,12 @@ my-app/
   └──────────────┬──────────────────────┘
                  │ Bearer <JWT>
                  ▼
-  Firebase Cloud Functions (Express)
+  Firebase v2 Cloud Functions (independent scaling)
   ┌─────────────────────────────────────┐
-  │  /auth      → OAuth 2.0 flow       │
-  │  /api/*     → Admin API (JWT auth)  │
-  │  /proxy/*   → App Proxy (HMAC)      │
-  │  /webhooks  → Webhooks (HMAC)       │
+  │  auth()      → OAuth 2.0 flow      │  (standalone, no Express)
+  │  api()       → Admin API (JWT)      │  (Express + middleware)
+  │  webhooks()  → Webhooks (HMAC)      │  (standalone, no Express)
+  │  proxy()     → App Proxy (HMAC)     │  (Express)
   └──────────────┬──────────────────────┘
                  │
                  ▼
@@ -212,6 +214,16 @@ my-app/
   └─────────────────────────────────────┘
 ```
 
+### Why split functions?
+
+| Benefit | How |
+|---------|-----|
+| **Faster webhooks** | `webhooks()` has no Express overhead — responds in milliseconds |
+| **Independent scaling** | Each function auto-scales based on its own traffic |
+| **Targeted deploys** | `firebase deploy --only functions:api` deploys just one function |
+| **Separate configs** | Each function gets its own memory, timeout, and concurrency |
+| **Lower cold starts** | Smaller functions = faster cold starts |
+
 ### Three Security Layers
 
 | Layer | Protects | How |
@@ -265,15 +277,56 @@ shopify app dev
 ### Deploy
 
 ```bash
-firebase deploy              # Everything
-firebase deploy --only functions   # Backend only
-firebase deploy --only hosting     # Frontend only
+firebase deploy                        # Everything
+firebase deploy --only functions       # All functions
+firebase deploy --only functions:auth  # Just auth function
+firebase deploy --only functions:api   # Just API function
+firebase deploy --only hosting         # Frontend only
 ```
 
 ---
 
 ## Extending Your App
 
+### Add a new Cloud Function
+
+This is the most common extension pattern. Create a new file, export a handler, and wire it up:
+
+**1. Create `functions/src/my-feature.ts`:**
+
+```typescript
+import type { Request, Response } from "firebase-functions/v2/https";
+import { db } from "./firebase";
+
+export async function myFeatureHandler(req: Request, res: Response) {
+  // Your logic here
+  res.json({ success: true });
+}
+```
+
+**2. Export it in `functions/src/index.ts`:**
+
+```typescript
+import { myFeatureHandler } from "./my-feature";
+
+export const myFeature = onRequest(
+  { memory: "256MiB", timeoutSeconds: 60 },
+  myFeatureHandler,
+);
+```
+
+**3. Add a rewrite in `firebase.json`:**
+
+```json
+{ "source": "/my-feature/**", "function": "myFeature" }
+```
+
+**4. Deploy just your function:**
+
+```bash
+firebase deploy --only functions:myFeature
+```
+
 ### Add admin API routes
 
 Edit `functions/src/admin-api.ts`:
@@ -304,7 +357,7 @@ Edit `functions/src/webhooks.ts` and register in `shopify.app.toml`:
 
 ```typescript
 case "orders/create": {
-  const order = req.body;
+  const order = body;
   // Your logic
   break;
 }
@@ -325,6 +378,27 @@ Create `web/settings.html`, use the same pattern, navigate with `App.navigate("/
 
 Use the `appSubscriptionCreate` GraphQL mutation in your admin API routes.
 
+### Add a scheduled function (cron)
+
+```typescript
+// functions/src/cleanup.ts
+import { onSchedule } from "firebase-functions/v2/scheduler";
+import { db } from "./firebase";
+
+export const dailyCleanup = onSchedule("every 24 hours", async () => {
+  // Clean up expired nonces, old data, etc.
+  const cutoff = new Date(Date.now() - 48 * 60 * 60 * 1000);
+  const old = await db.collection("authNonces")
+    .where("createdAt", "<", cutoff.toISOString()).get();
+  for (const doc of old.docs) await doc.ref.delete();
+});
+```
+
+Export it in `index.ts`:
+```typescript
+export { dailyCleanup } from "./cleanup";
+```
+
 ---
 
 ## Firebase Free Tier
@@ -364,8 +438,9 @@ These are **required** for Shopify App Store listing.
 | "Missing shop parameter" | Set **App URL** in Partner Dashboard to `https://PROJECT_ID.web.app` |
 | "HMAC verification failed" | Check `SHOPIFY_API_SECRET` in `functions/.env` |
 | "Invalid session token" | Verify `data-api-key` in `web/index.html` matches your API key |
-| Functions not receiving requests | Check `firebase.json` rewrites and run `firebase functions:list` |
+| Functions not receiving requests | Check `firebase.json` rewrites match function export names in `index.ts` |
 | Webhook failures | Must respond 200 within 5 seconds. Check `firebase functions:log` |
+| Individual function not deploying | Ensure export name in `index.ts` matches function name in `firebase.json` rewrite |
 
 ---
 
@@ -385,7 +460,7 @@ npm link  # Test locally: create-shopify-firebase-app test-app
 ## Related
 
 - [Shopify App Development](https://shopify.dev/docs/apps) — Official docs
-- [Firebase Cloud Functions](https://firebase.google.com/docs/functions) — Backend runtime
+- [Firebase v2 Cloud Functions](https://firebase.google.com/docs/functions) — Backend runtime (gen 2)
 - [Shopify App Bridge](https://shopify.dev/docs/api/app-bridge) — Embedded app SDK
 - [Shopify Admin GraphQL API](https://shopify.dev/docs/api/admin-graphql) — Store data API
 - [Theme App Extensions](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions) — Storefront blocks

package/lib/index.js

@@ -478,7 +478,8 @@ function printHelp() {
 
   ${c.bold}What you get:${c.reset}
 
-    ✔ Express + TypeScript Cloud Functions (OAuth, webhooks, GDPR)
+    ✔ Firebase v2 Cloud Functions (4 independent, auto-scaling functions)
+    ✔ Shopify API 2026-01 (latest) + OAuth, webhooks, GDPR
     ✔ Firestore for sessions and app data
     ✔ App Bridge embedded admin dashboard (vanilla HTML/JS)
     ✔ Theme App Extension for storefront UI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-shopify-firebase-app",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Create Shopify apps powered by Firebase — serverless, lightweight, zero-framework. The official alternative to Remix for Shopify + Firebase developers.",
   "keywords": [
     "shopify",

package/templates/firebase.json

@@ -3,20 +3,23 @@
     "public": "web",
     "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
     "rewrites": [
-      { "source": "/auth", "function": "app" },
-      { "source": "/auth/**", "function": "app" },
-      { "source": "/api", "function": "app" },
-      { "source": "/api/**", "function": "app" },
-      { "source": "/proxy", "function": "app" },
-      { "source": "/proxy/**", "function": "app" },
-      { "source": "/webhooks", "function": "app" },
-      { "source": "/webhooks/**", "function": "app" }
+      { "source": "/auth", "run": { "serviceId": "auth", "region": "us-central1" } },
+      { "source": "/auth/**", "run": { "serviceId": "auth", "region": "us-central1" } },
+      { "source": "/api", "run": { "serviceId": "api", "region": "us-central1" } },
+      { "source": "/api/**", "run": { "serviceId": "api", "region": "us-central1" } },
+      { "source": "/proxy", "run": { "serviceId": "proxy", "region": "us-central1" } },
+      { "source": "/proxy/**", "run": { "serviceId": "proxy", "region": "us-central1" } },
+      { "source": "/webhooks", "run": { "serviceId": "webhooks", "region": "us-central1" } },
+      { "source": "/webhooks/**", "run": { "serviceId": "webhooks", "region": "us-central1" } }
     ]
   },
-  "functions": {
-    "source": "functions",
-    "runtime": "nodejs20"
-  },
+  "functions": [
+    {
+      "source": "functions",
+      "codebase": "default",
+      "runtime": "nodejs20"
+    }
+  ],
   "firestore": {
     "rules": "firestore.rules",
     "indexes": "firestore.indexes.json"

package/templates/functions/package.json

@@ -9,21 +9,23 @@
     "build": "tsc",
     "serve": "npm run build && firebase emulators:start --only functions,firestore",
     "deploy": "firebase deploy --only functions",
+    "deploy:auth": "firebase deploy --only functions:auth",
+    "deploy:api": "firebase deploy --only functions:api",
+    "deploy:webhooks": "firebase deploy --only functions:webhooks",
+    "deploy:proxy": "firebase deploy --only functions:proxy",
     "deploy:all": "firebase deploy"
   },
   "dependencies": {
     "cors": "^2.8.5",
     "express": "^4.21.0",
-    "firebase-admin": "^12.7.0",
-    "firebase-functions": "^5.1.1",
-    "jsonwebtoken": "^9.0.2",
-    "node-fetch": "^2.7.0"
+    "firebase-admin": "^13.0.0",
+    "firebase-functions": "^6.3.0",
+    "jsonwebtoken": "^9.0.2"
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",
-    "@types/express": "^5.0.0",
+    "@types/express": "^4.17.21",
     "@types/jsonwebtoken": "^9.0.7",
-    "@types/node-fetch": "^2.6.12",
     "typescript": "^5.6.3"
   }
 }

package/templates/functions/src/admin-api.ts

@@ -1,5 +1,4 @@
 import { Router, Request, Response } from "express";
-import fetch from "node-fetch";
 import { verifySessionToken } from "./verify-token";
 import { getAccessToken } from "./auth";
 
@@ -8,6 +7,10 @@ export const adminApiRouter = Router();
 // All admin routes require session token verification
 adminApiRouter.use(verifySessionToken);
 
+// Shopify API version — update when Shopify releases new versions
+// Docs: https://shopify.dev/docs/api/usage/versioning
+const API_VERSION = "2026-01";
+
 // ─── Get shop info ───────────────────────────────────────────────────────
 adminApiRouter.get("/shop", async (req: Request, res: Response) => {
   const shop = (req as any).shopDomain;
@@ -20,7 +23,7 @@ adminApiRouter.get("/shop", async (req: Request, res: Response) => {
 
   try {
     const response = await fetch(
-      `https://${shop}/admin/api/2025-04/graphql.json`,
+      `https://${shop}/admin/api/${API_VERSION}/graphql.json`,
       {
         method: "POST",
         headers: {
@@ -54,7 +57,7 @@ adminApiRouter.get("/products/search", async (req: Request, res: Response) => {
 
   try {
     const response = await fetch(
-      `https://${shop}/admin/api/2025-04/graphql.json`,
+      `https://${shop}/admin/api/${API_VERSION}/graphql.json`,
       {
         method: "POST",
         headers: {
@@ -108,9 +111,15 @@ adminApiRouter.get("/products/search", async (req: Request, res: Response) => {
 });
 
 // ──────────────────────────────────────────────────────────────────────────
-// Add your admin API routes below.
-// All routes are protected by session token verification.
+// HOW TO ADD A NEW ADMIN API ROUTE:
+//
+//   adminApiRouter.post("/my-endpoint", async (req, res) => {
+//     const shop = (req as any).shopDomain;
+//     const accessToken = await getAccessToken(shop);
+//     // Call Shopify Admin API, write to Firestore, etc.
+//     res.json({ success: true });
+//   });
 //
-//   const shop = (req as any).shopDomain;
-//   const accessToken = await getAccessToken(shop);
+// All routes are automatically protected by JWT session token verification.
+// Deploy: firebase deploy --only functions:api
 // ──────────────────────────────────────────────────────────────────────────

package/templates/functions/src/auth.ts

@@ -1,14 +1,33 @@
-import { Router, Request, Response } from "express";
 import crypto from "crypto";
-import fetch from "node-fetch";
 import { getConfig } from "./config";
 import { db } from "./firebase";
+import type { Request } from "firebase-functions/v2/https";
+
+/**
+ * Standalone OAuth handler — no Express, no middleware overhead.
+ *
+ * Routes:
+ *   GET /auth           → Start OAuth (redirect to Shopify consent screen)
+ *   GET /auth/callback  → Handle callback (exchange code, store session)
+ */
+export async function authHandler(req: Request, res: any): Promise<void> {
+  const urlPath = req.path;
+
+  if (req.method !== "GET") {
+    res.status(405).send("Method not allowed");
+    return;
+  }
 
-export const authRouter = Router();
+  if (urlPath === "/auth/callback") {
+    await handleCallback(req, res);
+  } else {
+    handleStart(req, res);
+  }
+}
 
 // ─── Step 1: Start OAuth ─────────────────────────────────────────────────
 // Merchant clicks "Install" → redirect to Shopify consent screen.
-authRouter.get("/", (req: Request, res: Response) => {
+function handleStart(req: Request, res: any): void {
   const { shop } = req.query;
   if (!shop || typeof shop !== "string") {
     res.status(400).send("Missing shop parameter");
@@ -33,11 +52,11 @@ authRouter.get("/", (req: Request, res: Response) => {
     `&state=${nonce}`;
 
   res.redirect(authUrl);
-});
+}
 
 // ─── Step 2: OAuth Callback ──────────────────────────────────────────────
 // Shopify redirects back with code + HMAC. Verify, exchange, store session.
-authRouter.get("/callback", async (req: Request, res: Response) => {
+async function handleCallback(req: Request, res: any): Promise<void> {
   const { shop, code, hmac, state } = req.query;
 
   if (!shop || !code || !hmac) {
@@ -47,7 +66,7 @@ authRouter.get("/callback", async (req: Request, res: Response) => {
 
   const config = getConfig();
 
-  // Verify HMAC (primary security check — timing-safe)
+  // Verify HMAC (timing-safe comparison)
   const queryParams = { ...req.query };
   delete queryParams.hmac;
   delete queryParams.signature;
@@ -120,7 +139,7 @@ authRouter.get("/callback", async (req: Request, res: Response) => {
     console.error("OAuth error:", err);
     res.status(500).send("OAuth error");
   }
-});
+}
 
 // Helper: get stored access token for a shop
 export async function getAccessToken(shop: string): Promise<string | null> {

package/templates/functions/src/index.ts

@@ -1,40 +1,93 @@
-import * as functions from "firebase-functions";
-import "./firebase"; // Initialize Firebase first — must be before other imports
+/**
+ * Cloud Function exports — each function scales independently.
+ *
+ * Firebase v2 (gen 2) functions run on Cloud Run with per-function
+ * concurrency, memory, timeout, and min-instance settings.
+ *
+ * Architecture:
+ *   auth      — OAuth 2.0 install + callback (standalone, no Express)
+ *   api       — Admin dashboard API routes (Express + JWT middleware)
+ *   webhooks  — Webhook handlers (standalone, no Express — fast cold starts)
+ *   proxy     — Storefront App Proxy routes (Express + HMAC verification)
+ *
+ * Adding a new function:
+ *   1. Create a new file in src/ (e.g. src/cron.ts)
+ *   2. Export a handler from it
+ *   3. Import and re-export here with desired options
+ *   4. Add a rewrite in firebase.json if it needs an HTTP endpoint
+ *   5. Run: firebase deploy --only functions:yourFunction
+ *
+ * Docs: https://firebase.google.com/docs/functions/http-events?gen=2nd
+ */
+
+import "./firebase"; // Initialize Firebase Admin SDK — must be first
+
+import { onRequest } from "firebase-functions/v2/https";
 import express from "express";
 import cors from "cors";
-import { authRouter } from "./auth";
+import { authHandler } from "./auth";
 import { adminApiRouter } from "./admin-api";
 import { proxyRouter } from "./proxy";
-import { webhookRouter } from "./webhooks";
-
-const expressApp = express();
-expressApp.use(cors({ origin: true }));
-
-// Capture raw body for webhook HMAC verification.
-// Shopify signs the raw request body — we need it before JSON parsing.
-expressApp.use(
-  express.json({
-    limit: "2mb",
-    verify: (req: any, _res, buf) => {
-      req.rawBody = buf.toString("utf8");
-    },
-  }),
+import { webhookHandler } from "./webhooks";
+
+// ─── auth: OAuth 2.0 install + callback ──────────────────────────────────
+// Standalone handler (no Express overhead). Handles:
+//   GET /auth         → redirect to Shopify consent screen
+//   GET /auth/callback → exchange code for access token
+export const auth = onRequest(
+  { memory: "256MiB", timeoutSeconds: 30, invoker: "public" },
+  authHandler,
+);
+
+// ─── api: Admin dashboard API ────────────────────────────────────────────
+// Express app with JWT session token middleware on all routes.
+// Add routes in src/admin-api.ts.
+const apiApp = express();
+apiApp.use(cors({ origin: true }));
+apiApp.use(express.json());
+apiApp.use("/api", adminApiRouter);
+
+export const api = onRequest(
+  { memory: "256MiB", timeoutSeconds: 60, invoker: "public" },
+  apiApp,
 );
-expressApp.use(express.urlencoded({ extended: true }));
-
-// ─── Routes ────────────────────────────────────────────────────────────────
-expressApp.use("/auth", authRouter);       // OAuth install + callback
-expressApp.use("/api", adminApiRouter);     // Admin dashboard API (JWT auth)
-expressApp.use("/proxy", proxyRouter);      // App Proxy routes (HMAC auth)
-expressApp.use("/webhooks", webhookRouter); // Webhook handlers
-
-// Health check
-expressApp.get("/", (_req, res) => {
-  res.json({ status: "ok", timestamp: new Date().toISOString() });
-});
-
-// Export as a single Cloud Function.
-// Firebase Hosting rewrites (firebase.json) forward requests here.
-export const app = functions
-  .runWith({ timeoutSeconds: 60, memory: "256MB" })
-  .https.onRequest(expressApp);
+
+// ─── webhooks: Shopify webhook handlers ──────────────────────────────────
+// Standalone handler for maximum speed. Must respond 200 within 5 seconds.
+// No Express, no CORS, no JSON parsing — just raw body HMAC verification.
+export const webhooks = onRequest(
+  { memory: "256MiB", timeoutSeconds: 10, invoker: "public" },
+  webhookHandler,
+);
+
+// ─── proxy: Storefront App Proxy routes ──────────────────────────────────
+// Express app for storefront-facing endpoints.
+// Add routes in src/proxy.ts. Enable App Proxy in shopify.app.toml.
+const proxyApp = express();
+proxyApp.use(cors({ origin: true }));
+proxyApp.use(express.json());
+proxyApp.use("/proxy", proxyRouter);
+
+export const proxy = onRequest(
+  { memory: "256MiB", timeoutSeconds: 30, invoker: "public" },
+  proxyApp,
+);
+
+// ──────────────────────────────────────────────────────────────────────────
+// HOW TO ADD A NEW FUNCTION:
+//
+//   // 1. Create src/my-feature.ts with your handler
+//   import { myFeatureHandler } from "./my-feature";
+//
+//   // 2. Export it here with desired options
+//   export const myFeature = onRequest(
+//     { memory: "256MiB", timeoutSeconds: 60, invoker: "public" },
+//     myFeatureHandler,
+//   );
+//
+//   // 3. Add rewrite in firebase.json:
+//   //    { "source": "/my-feature/**", "run": { "serviceId": "myFeature", "region": "us-central1" } }
+//
+//   // 4. Deploy only your function:
+//   //    firebase deploy --only functions:myFeature
+// ──────────────────────────────────────────────────────────────────────────

package/templates/functions/src/proxy.ts

@@ -44,7 +44,15 @@ proxyRouter.get("/hello", (req: Request, res: Response) => {
 });
 
 // ──────────────────────────────────────────────────────────────────────────
-// Add storefront-facing routes below.
-// Always verify the proxy signature first.
-// Enable App Proxy in shopify.app.toml.
+// HOW TO ADD A NEW PROXY ROUTE:
+//
+//   proxyRouter.get("/my-route", (req, res) => {
+//     if (!verifyProxySignature(req.query as Record<string, any>)) {
+//       return res.status(403).json({ error: "Invalid signature" });
+//     }
+//     res.json({ hello: "storefront" });
+//   });
+//
+// Enable App Proxy in shopify.app.toml (uncomment the [app_proxy] section).
+// Deploy: firebase deploy --only functions:proxy
 // ──────────────────────────────────────────────────────────────────────────

package/templates/functions/src/webhooks.ts

@@ -1,16 +1,14 @@
-import { Router, Request, Response } from "express";
 import crypto from "crypto";
 import { getConfig } from "./config";
 import { db } from "./firebase";
-
-export const webhookRouter = Router();
+import type { Request } from "firebase-functions/v2/https";
 
 // ─── Verify Shopify Webhook HMAC ─────────────────────────────────────────
-function verifyWebhookHmac(rawBody: string, hmacHeader: string): boolean {
+function verifyWebhookHmac(rawBody: Buffer, hmacHeader: string): boolean {
   const config = getConfig();
   const hash = crypto
     .createHmac("sha256", config.apiSecret)
-    .update(rawBody, "utf8")
+    .update(rawBody)
     .digest("base64");
 
   try {
@@ -20,18 +18,26 @@ function verifyWebhookHmac(rawBody: string, hmacHeader: string): boolean {
   }
 }
 
-// ─── Webhook Handler ─────────────────────────────────────────────────────
-// All topics route to this single POST endpoint.
-// Topic is identified via X-Shopify-Topic header.
-// IMPORTANT: Respond 200 within 5 seconds. Do heavy work async.
-webhookRouter.post("/", async (req: Request, res: Response) => {
+/**
+ * Standalone webhook handler — no Express, no middleware.
+ *
+ * Why standalone? Webhooks must respond 200 within 5 seconds.
+ * Skipping Express middleware means faster cold starts and less overhead.
+ * Uses req.rawBody (provided natively by Firebase v2) for HMAC verification.
+ */
+export async function webhookHandler(req: Request, res: any): Promise<void> {
+  // Only accept POST
+  if (req.method !== "POST") {
+    res.status(405).send("Method not allowed");
+    return;
+  }
+
   const hmac = req.headers["x-shopify-hmac-sha256"] as string;
   const topic = req.headers["x-shopify-topic"] as string;
   const shop = req.headers["x-shopify-shop-domain"] as string;
 
-  // Verify HMAC
-  const rawBody = (req as any).rawBody;
-  if (rawBody && hmac && !verifyWebhookHmac(rawBody, hmac)) {
+  // Verify HMAC using rawBody (Buffer, provided by Firebase v2)
+  if (req.rawBody && hmac && !verifyWebhookHmac(req.rawBody, hmac)) {
     console.error("Webhook HMAC verification failed");
     res.status(401).send("Unauthorized");
     return;
@@ -39,6 +45,14 @@ webhookRouter.post("/", async (req: Request, res: Response) => {
 
   console.log(`Webhook: ${topic} from ${shop}`);
 
+  // Parse body
+  let body: any = {};
+  try {
+    body = JSON.parse(req.rawBody?.toString("utf8") || "{}");
+  } catch {
+    // Non-JSON webhook payloads are rare but valid
+  }
+
   switch (topic) {
     // ── App lifecycle ──────────────────────────────────────────────────
     case "app/uninstalled": {
@@ -73,5 +87,24 @@ webhookRouter.post("/", async (req: Request, res: Response) => {
       console.log(`Unhandled webhook: ${topic}`);
   }
 
+  // Always respond 200 quickly — do heavy work asynchronously
   res.status(200).send("OK");
-});
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// HOW TO ADD A NEW WEBHOOK HANDLER:
+//
+//   1. Register the topic in shopify.app.toml:
+//      [[webhooks.subscriptions]]
+//      topics = [ "orders/create" ]
+//      uri = "{{APP_URL}}/webhooks"
+//
+//   2. Add a case to the switch above:
+//      case "orders/create": {
+//        const order = body;
+//        // Your logic here
+//        break;
+//      }
+//
+//   3. Deploy: firebase deploy --only functions:webhooks
+// ──────────────────────────────────────────────────────────────────────────

package/templates/shopify.app.toml

@@ -15,7 +15,7 @@ redirect_urls = [
 ]
 
 [webhooks]
-api_version = "2025-04"
+api_version = "2026-01"
 
   # App lifecycle
   [[webhooks.subscriptions]]