create-shopify-firebase-app 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # create-shopify-firebase-app
 
-> Create Shopify apps powered by Firebase. One command. Zero framework. Fully serverless.
+> Build and run Shopify apps for free. Pay nothing until you have real traffic. One command. Zero framework. Fully serverless.
 
 [![npm version](https://img.shields.io/npm/v/create-shopify-firebase-app.svg)](https://www.npmjs.com/package/create-shopify-firebase-app)
 [![Downloads](https://img.shields.io/npm/dm/create-shopify-firebase-app.svg)](https://www.npmjs.com/package/create-shopify-firebase-app)
@@ -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`.
 
@@ -117,31 +117,35 @@ shopify app dev
 
 ---
 
-## Why Firebase instead of Remix?
+## Why Firebase?
+
+**$0/month to run your Shopify app. No credit card. No server. No bill until you're big.**
+
+Most Shopify app developers pay for hosting before they even have users. With Firebase, you deploy for free and only start paying when your app serves thousands of stores daily. Even at 50,000 installed stores, you're looking at ~$5/month. Try getting that from Vercel or Heroku.
 
 | | `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) |
 | **Auth** | `@shopify/shopify-app-remix` | Manual OAuth (140 lines, you own it) |
 | **Build** | Webpack / Vite | `tsc` (TypeScript compiler, no bundler) |
 | **Deploy** | Varies | `firebase deploy` (one command) |
-| **Cost** | $5-25/month hosting | Free tier covers most apps |
+| **Cost** | $5-25/month from day one | **$0/month** — free until you scale |
 | **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) |
 
 ### When to use this
 
+- You want to **launch for free** and only pay when your app takes off
 - Custom apps for a single merchant
 - Public apps with simple admin UIs
 - Teams already using Firebase / Google Cloud
 - You want to understand every line of your app
-- You want free/cheap serverless hosting
 
 ### When to use Remix instead
 
@@ -155,18 +159,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 +191,8 @@ my-app/
 
 ## Architecture
 
+Each function scales independently on Cloud Run (Firebase v2 / gen 2):
+
 ```
   Shopify Admin (iframe)
   ┌─────────────────────────────────────┐
@@ -195,12 +201,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 +218,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 +281,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 +361,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,21 +382,68 @@ 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
+## How Many Stores Can You Run for Free?
+
+Firebase's free tier is generous. Here's what it actually means for a Shopify app:
+
+### Per-store usage (typical Shopify app)
+
+| Action | Function calls | Firestore reads | Firestore writes |
+|--------|---------------|-----------------|------------------|
+| Merchant opens admin dashboard | 5 | 5 | 0 |
+| Webhooks (orders, inventory) | 5 | 5 | 2 |
+| **Total per active store/day** | **~10** | **~10** | **~2** |
+
+### Free tier capacity
+
+| Firebase Resource | Free Limit | Stores Supported |
+|-------------------|-----------|-----------------|
+| Cloud Functions | 2M invocations/month (~66K/day) | **~6,600 daily active stores** |
+| Firestore reads | 50K/day | **~5,000 daily active stores** |
+| Firestore writes | 20K/day | **~10,000 daily active stores** |
+| Hosting bandwidth | 360 MB/day | **~7,000 page loads/day** (CDN-cached after first load) |
+
+**Bottleneck: Firestore reads at ~5,000 daily active stores.**
+
+Not every installed merchant opens your app daily. With a typical 20% daily active rate:
+
+> **Free tier supports ~25,000 installed stores** with normal usage patterns. That's $0/month.
+
+### When you outgrow free (Blaze pay-as-you-go)
 
-The Spark (free) plan covers most Shopify apps:
+| Installed Stores | Daily Active | Monthly Cost |
+|-----------------|-------------|-------------|
+| 1 - 25,000 | up to 5,000 | **$0 (free)** |
+| 50,000 | ~10,000 | **~$5/month** |
+| 100,000 | ~20,000 | **~$15/month** |
+| 500,000 | ~100,000 | **~$80/month** |
 
-| Resource | Free Limit |
-|----------|-----------|
-| Cloud Functions | 2M invocations/month |
-| Firestore reads | 50K/day |
-| Firestore writes | 20K/day |
-| Hosting storage | 10 GB |
-| Hosting transfer | 360 MB/day |
+Compare that to Vercel/Heroku at **$25-100/month from day one**, before you even have your first user.
 
-Need more? The Blaze plan (pay-as-you-go) costs most apps **under $5/month**.
+No credit card required to start. No server to manage. No bill until you're successful.
 
 ---
 
@@ -364,8 +468,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 +490,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.1",
   "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]]