create-shopify-firebase-app 1.3.0 → 2.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-shopify-firebase-app",
-  "version": "1.3.0",
-  "description": "Create Shopify apps powered by Firebase — serverless, lightweight, zero-framework. The official alternative to Remix for Shopify + Firebase developers.",
+  "version": "2.0.1",
+  "description": "Create Shopify apps powered by Firebase — multi-page dashboard, App Bridge, Polaris components, TypeScript or JavaScript. Deploy for free.",
   "keywords": [
     "shopify",
     "firebase",

package/templates/js/functions/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "shopify-firebase-functions",
+  "private": true,
+  "main": "src/index.js",
+  "engines": {
+    "node": "20"
+  },
+  "scripts": {
+    "serve": "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": "^13.0.0",
+    "firebase-functions": "^6.3.0",
+    "jsonwebtoken": "^9.0.2"
+  }
+}

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

@@ -0,0 +1,292 @@
+const { Router } = require("express");
+const { verifySessionToken } = require("./verify-token");
+const { getAccessToken } = require("./auth");
+const { db } = require("./firebase");
+
+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";
+
+// Default app settings — returned when no settings are saved yet
+const DEFAULT_SETTINGS = {
+  greeting: "Welcome to our app!",
+  theme: "auto",
+  notifications: true,
+  customCss: "",
+};
+
+// ─── Get shop info ───────────────────────────────────────────────────────
+adminApiRouter.get("/shop", async (req, res) => {
+  const shop = req.shopDomain;
+  const accessToken = await getAccessToken(shop);
+
+  if (!accessToken) {
+    res.status(401).json({ error: "Shop not authenticated" });
+    return;
+  }
+
+  try {
+    const response = await fetch(
+      `https://${shop}/admin/api/${API_VERSION}/graphql.json`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Shopify-Access-Token": accessToken,
+        },
+        body: JSON.stringify({
+          query: `{
+            shop {
+              name
+              email
+              myshopifyDomain
+              url
+              primaryDomain { url host }
+              plan { displayName partnerDevelopment shopifyPlus }
+              currencyCode
+              ianaTimezone
+              billingAddress { country countryCodeV2 }
+              productCount: productsCount { count }
+            }
+          }`,
+        }),
+      },
+    );
+
+    const data = await response.json();
+    res.json({ shop: data.data?.shop });
+  } catch (err) {
+    console.error("Shop info error:", err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ─── Search products ────────────────────────────────────────────────────
+// NOTE: This route MUST be defined before /products/:id so Express
+// doesn't match "search" as a product ID.
+adminApiRouter.get("/products/search", async (req, res) => {
+  const shop = req.shopDomain;
+  const query = req.query.q || "";
+  const accessToken = await getAccessToken(shop);
+
+  if (!accessToken) {
+    res.status(401).json({ error: "Shop not authenticated" });
+    return;
+  }
+
+  try {
+    const response = await fetch(
+      `https://${shop}/admin/api/${API_VERSION}/graphql.json`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Shopify-Access-Token": accessToken,
+        },
+        body: JSON.stringify({
+          query: `
+            query SearchProducts($query: String!) {
+              products(first: 10, query: $query) {
+                edges {
+                  node {
+                    id
+                    title
+                    handle
+                    status
+                    featuredImage { url }
+                    variants(first: 1) {
+                      edges { node { id price } }
+                    }
+                    priceRangeV2 {
+                      minVariantPrice { amount currencyCode }
+                    }
+                  }
+                }
+              }
+            }
+          `,
+          variables: { query },
+        }),
+      },
+    );
+
+    const data = await response.json();
+    const products = (data.data?.products?.edges || []).map((edge) => ({
+      id: edge.node.id,
+      title: edge.node.title,
+      handle: edge.node.handle,
+      status: edge.node.status,
+      image: edge.node.featuredImage?.url || null,
+      variantId: edge.node.variants.edges[0]?.node.id || null,
+      price: edge.node.priceRangeV2?.minVariantPrice?.amount,
+      currency: edge.node.priceRangeV2?.minVariantPrice?.currencyCode,
+    }));
+
+    res.json({ products });
+  } catch (err) {
+    console.error("Product search error:", err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ─── Get product detail ─────────────────────────────────────────────────
+adminApiRouter.get("/products/:id", async (req, res) => {
+  const shop = req.shopDomain;
+  const accessToken = await getAccessToken(shop);
+
+  if (!accessToken) {
+    res.status(401).json({ error: "Shop not authenticated" });
+    return;
+  }
+
+  const productId = req.params.id;
+  // Support both raw numeric IDs and full GID format
+  const gid = productId.startsWith("gid://")
+    ? productId
+    : `gid://shopify/Product/${productId}`;
+
+  try {
+    const response = await fetch(
+      `https://${shop}/admin/api/${API_VERSION}/graphql.json`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Shopify-Access-Token": accessToken,
+        },
+        body: JSON.stringify({
+          query: `
+            query GetProduct($id: ID!) {
+              product(id: $id) {
+                id
+                title
+                handle
+                description
+                status
+                vendor
+                productType
+                tags
+                totalInventory
+                priceRangeV2 {
+                  maxVariantPrice { amount currencyCode }
+                  minVariantPrice { amount currencyCode }
+                }
+                featuredImage { url altText }
+                images(first: 5) {
+                  edges { node { url altText } }
+                }
+                variants(first: 20) {
+                  edges {
+                    node {
+                      id
+                      title
+                      price
+                      sku
+                      inventoryQuantity
+                      selectedOptions { name value }
+                    }
+                  }
+                }
+              }
+            }
+          `,
+          variables: { id: gid },
+        }),
+      },
+    );
+
+    const data = await response.json();
+    const product = data.data?.product;
+
+    if (!product) {
+      res.status(404).json({ error: "Product not found" });
+      return;
+    }
+
+    res.json({ product });
+  } catch (err) {
+    console.error("Product detail error:", err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ─── Get app settings ───────────────────────────────────────────────────
+adminApiRouter.get("/settings", async (req, res) => {
+  const shop = req.shopDomain;
+
+  try {
+    const doc = await db.collection("appSettings").doc(shop).get();
+
+    if (!doc.exists) {
+      res.json({ settings: { ...DEFAULT_SETTINGS } });
+      return;
+    }
+
+    // Merge with defaults so new keys are always present
+    res.json({ settings: { ...DEFAULT_SETTINGS, ...doc.data() } });
+  } catch (err) {
+    console.error("Get settings error:", err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ─── Save app settings ──────────────────────────────────────────────────
+adminApiRouter.post("/settings", async (req, res) => {
+  const shop = req.shopDomain;
+  const body = req.body;
+
+  if (!body || typeof body !== "object") {
+    res.status(400).json({ error: "Request body must be a JSON object" });
+    return;
+  }
+
+  // Only allow known setting keys
+  const allowedKeys = Object.keys(DEFAULT_SETTINGS);
+  const settings = {};
+
+  for (const key of allowedKeys) {
+    if (key in body) {
+      settings[key] = body[key];
+    }
+  }
+
+  if (Object.keys(settings).length === 0) {
+    res.status(400).json({
+      error: "No valid settings provided",
+      allowedKeys,
+    });
+    return;
+  }
+
+  try {
+    await db.collection("appSettings").doc(shop).set(settings, { merge: true });
+
+    // Return the full merged settings
+    const doc = await db.collection("appSettings").doc(shop).get();
+    res.json({ settings: { ...DEFAULT_SETTINGS, ...doc.data() } });
+  } catch (err) {
+    console.error("Save settings error:", err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// HOW TO ADD A NEW ADMIN API ROUTE:
+//
+//   adminApiRouter.post("/my-endpoint", async (req, res) => {
+//     const shop = req.shopDomain;
+//     const accessToken = await getAccessToken(shop);
+//     // Call Shopify Admin API, write to Firestore, etc.
+//     res.json({ success: true });
+//   });
+//
+// All routes are automatically protected by JWT session token verification.
+// Deploy: firebase deploy --only functions:api
+// ──────────────────────────────────────────────────────────────────────────
+
+module.exports = { adminApiRouter };

package/templates/js/functions/src/auth.js

@@ -0,0 +1,147 @@
+const crypto = require("crypto");
+const { getConfig } = require("./config");
+const { db } = require("./firebase");
+
+/**
+ * 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)
+ */
+async function authHandler(req, res) {
+  const urlPath = req.path;
+
+  if (req.method !== "GET") {
+    res.status(405).send("Method not allowed");
+    return;
+  }
+
+  if (urlPath === "/auth/callback") {
+    await handleCallback(req, res);
+  } else {
+    handleStart(req, res);
+  }
+}
+
+// ─── Step 1: Start OAuth ─────────────────────────────────────────────────
+// Merchant clicks "Install" -> redirect to Shopify consent screen.
+function handleStart(req, res) {
+  const { shop } = req.query;
+  if (!shop || typeof shop !== "string") {
+    res.status(400).send("Missing shop parameter");
+    return;
+  }
+
+  const config = getConfig();
+  const nonce = crypto.randomBytes(16).toString("hex");
+  const redirectUri = `${config.appUrl}/auth/callback`;
+
+  // Store nonce for CSRF protection
+  db.collection("authNonces").doc(nonce).set({
+    shop,
+    createdAt: new Date().toISOString(),
+  });
+
+  const authUrl =
+    `https://${shop}/admin/oauth/authorize` +
+    `?client_id=${config.apiKey}` +
+    `&scope=${config.scopes}` +
+    `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+    `&state=${nonce}`;
+
+  res.redirect(authUrl);
+}
+
+// ─── Step 2: OAuth Callback ──────────────────────────────────────────────
+// Shopify redirects back with code + HMAC. Verify, exchange, store session.
+async function handleCallback(req, res) {
+  const { shop, code, hmac, state } = req.query;
+
+  if (!shop || !code || !hmac) {
+    res.status(400).send("Missing required parameters");
+    return;
+  }
+
+  const config = getConfig();
+
+  // Verify HMAC (timing-safe comparison)
+  const queryParams = { ...req.query };
+  delete queryParams.hmac;
+  delete queryParams.signature;
+  const message = Object.keys(queryParams)
+    .sort()
+    .map((key) => `${key}=${queryParams[key]}`)
+    .join("&");
+  const generatedHmac = crypto
+    .createHmac("sha256", config.apiSecret)
+    .update(message)
+    .digest("hex");
+
+  const hmacBuffer = Buffer.from(hmac);
+  const generatedBuffer = Buffer.from(generatedHmac);
+  if (
+    hmacBuffer.length !== generatedBuffer.length ||
+    !crypto.timingSafeEqual(generatedBuffer, hmacBuffer)
+  ) {
+    res.status(403).send("HMAC verification failed");
+    return;
+  }
+
+  // Clean up nonce
+  if (state) {
+    const nonceDoc = await db.collection("authNonces").doc(state).get();
+    if (nonceDoc.exists) await nonceDoc.ref.delete();
+  }
+
+  // Exchange code for access token
+  try {
+    const tokenResponse = await fetch(
+      `https://${shop}/admin/oauth/access_token`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          client_id: config.apiKey,
+          client_secret: config.apiSecret,
+          code,
+        }),
+      },
+    );
+
+    if (!tokenResponse.ok) {
+      const errorText = await tokenResponse.text();
+      console.error("Token exchange failed:", errorText);
+      res.status(500).send("Token exchange failed");
+      return;
+    }
+
+    const tokenData = await tokenResponse.json();
+
+    // Store session in Firestore
+    await db
+      .collection("shopSessions")
+      .doc(shop)
+      .set({
+        shop,
+        accessToken: tokenData.access_token,
+        scope: tokenData.scope,
+        installedAt: new Date().toISOString(),
+      });
+
+    console.log(`App installed for shop: ${shop}`);
+    res.redirect(`https://${shop}/admin/apps/${config.apiKey}`);
+  } catch (err) {
+    console.error("OAuth error:", err);
+    res.status(500).send("OAuth error");
+  }
+}
+
+// Helper: get stored access token for a shop
+async function getAccessToken(shop) {
+  const doc = await db.collection("shopSessions").doc(shop).get();
+  if (!doc.exists) return null;
+  return doc.data()?.accessToken || null;
+}
+
+module.exports = { authHandler, getAccessToken };

package/templates/js/functions/src/config.js

@@ -0,0 +1,14 @@
+// Centralized config from environment variables.
+// Firebase Functions auto-loads .env files from the functions/ directory.
+// Docs: https://firebase.google.com/docs/functions/config-env
+
+function getConfig() {
+  return {
+    apiKey: process.env.SHOPIFY_API_KEY || "",
+    apiSecret: process.env.SHOPIFY_API_SECRET || "",
+    scopes: process.env.SCOPES || "read_products",
+    appUrl: process.env.APP_URL || "",
+  };
+}
+
+module.exports = { getConfig };

package/templates/js/functions/src/firebase.js

@@ -0,0 +1,12 @@
+const admin = require("firebase-admin");
+
+// Initialize Firebase Admin SDK once.
+// Credentials are auto-detected on Firebase infrastructure.
+// For local dev, use `firebase emulators:start`.
+if (!admin.apps.length) {
+  admin.initializeApp();
+}
+
+const db = admin.firestore();
+
+module.exports = { db };

package/templates/js/functions/src/index.js

@@ -0,0 +1,93 @@
+/**
+ * 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.js)
+ *   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
+ */
+
+require("./firebase"); // Initialize Firebase Admin SDK — must be first
+
+const { onRequest } = require("firebase-functions/v2/https");
+const express = require("express");
+const cors = require("cors");
+const { authHandler } = require("./auth");
+const { adminApiRouter } = require("./admin-api");
+const { proxyRouter } = require("./proxy");
+const { webhookHandler } = require("./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
+exports.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.js.
+const apiApp = express();
+apiApp.use(cors({ origin: true }));
+apiApp.use(express.json());
+apiApp.use("/api", adminApiRouter);
+
+exports.api = onRequest(
+  { memory: "256MiB", timeoutSeconds: 60, invoker: "public" },
+  apiApp,
+);
+
+// ─── 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.
+exports.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.js. Enable App Proxy in shopify.app.toml.
+const proxyApp = express();
+proxyApp.use(cors({ origin: true }));
+proxyApp.use(express.json());
+proxyApp.use("/proxy", proxyRouter);
+
+exports.proxy = onRequest(
+  { memory: "256MiB", timeoutSeconds: 30, invoker: "public" },
+  proxyApp,
+);
+
+// ──────────────────────────────────────────────────────────────────────────
+// HOW TO ADD A NEW FUNCTION:
+//
+//   // 1. Create src/my-feature.js with your handler
+//   const { myFeatureHandler } = require("./my-feature");
+//
+//   // 2. Export it here with desired options
+//   exports.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/js/functions/src/proxy.js

@@ -0,0 +1,60 @@
+const { Router } = require("express");
+const crypto = require("crypto");
+const { getConfig } = require("./config");
+
+const proxyRouter = Router();
+
+// ─── Verify Shopify App Proxy Signature ──────────────────────────────────
+// Docs: https://shopify.dev/docs/apps/build/online-store/app-proxies
+function verifyProxySignature(query) {
+  const config = getConfig();
+  const signature = query.signature;
+  if (!signature) return false;
+
+  const params = { ...query };
+  delete params.signature;
+
+  // App proxy concatenates without & (different from OAuth HMAC)
+  const message = Object.keys(params)
+    .sort()
+    .map((key) => `${key}=${params[key]}`)
+    .join("");
+
+  const generated = crypto
+    .createHmac("sha256", config.apiSecret)
+    .update(message)
+    .digest("hex");
+
+  const sigBuffer = Buffer.from(signature);
+  const genBuffer = Buffer.from(generated);
+  if (sigBuffer.length !== genBuffer.length) return false;
+  return crypto.timingSafeEqual(genBuffer, sigBuffer);
+}
+
+// ─── Example storefront endpoint ─────────────────────────────────────────
+// Accessible at: https://your-store.myshopify.com/apps/{subpath}/hello
+proxyRouter.get("/hello", (req, res) => {
+  if (!verifyProxySignature(req.query)) {
+    res.status(403).json({ error: "Invalid signature" });
+    return;
+  }
+
+  const shop = req.query.shop;
+  res.json({ message: `Hello from the app proxy! Shop: ${shop}` });
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// HOW TO ADD A NEW PROXY ROUTE:
+//
+//   proxyRouter.get("/my-route", (req, res) => {
+//     if (!verifyProxySignature(req.query)) {
+//       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
+// ──────────────────────────────────────────────────────────────────────────
+
+module.exports = { proxyRouter };