create-shopify-firebase-app 1.1.2 → 1.2.0

package/README.md

@@ -18,6 +18,25 @@ npx create-shopify-firebase-app my-app
 
 ---
 
+## Table of Contents
+
+- [What is this?](#what-is-this)
+- [Quick Start](#quick-start)
+- [Why Firebase?](#why-firebase)
+- [What's Inside](#whats-inside)
+- [Architecture](#architecture)
+- [CLI Usage](#cli-usage)
+- [Development](#development)
+- [Extending Your App](#extending-your-app)
+- [How Many Stores Can You Run for Free?](#how-many-stores-can-you-run-for-free)
+- [GDPR Compliance](#gdpr-compliance)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Related](#related)
+- [License](#license)
+
+---
+
 ## What is this?
 
 The **Firebase alternative** to `shopify app init`. Instead of Remix + Prisma + Vercel, you get:
@@ -44,53 +63,74 @@ One `npx` command scaffolds everything, installs dependencies, wires up Firebase
 | Firebase CLI | `npm i -g firebase-tools` | Yes, installed automatically if missing |
 | Shopify CLI | `npm i -g @shopify/cli` | Yes, installed automatically if missing |
 
-### 1. Create your Shopify app
-
-Go to [partners.shopify.com](https://partners.shopify.com/) → **Apps** → **Create app** → **Create app manually**.
-Copy the **Client ID** (API Key) and **Client Secret** (API Secret).
-
-### 2. Create your Firebase project
-
-Go to [console.firebase.google.com](https://console.firebase.google.com/) → **Add project**.
-Enable **Cloud Firestore** (production mode). Note the **Project ID**.
-
-### 3. Run the scaffold
+### 1. Run the scaffold
 
 ```bash
 npx create-shopify-firebase-app my-app
 ```
 
-The interactive CLI asks for your credentials and does the rest:
+The interactive CLI guides you through everything — creating your Shopify app, setting up Firebase, and wiring it all together:
 
 ```
-  SHOPIFY + FIREBASE   Create a new Shopify app
+  🛍️  +  🔥  create-shopify-firebase-app
+  Serverless Shopify apps — free until you scale
 
-  ✔ Project directory name: my-app
-  ✔ App name: My App
-  ✔ Shopify API Key: abc123...
-  ✔ Shopify API Secret: ********
-  ✔ API Scopes: read_products
-  ✔ Firebase Project ID: my-app-12345
+  === App Configuration ===
 
-  [1/6] Scaffolding project...
-  ✔ Created 27 files in my-app/
+  ? Project directory name: my-app
+  ? App name (shown in Shopify admin): My App
+  ? What kind of app are you building?
+    ❯ Public app — list on the Shopify App Store
+      Custom app — built for a single store
 
-  [2/6] Installing dependencies...
-  ✔ Dependencies installed
+  === Shopify Setup ===
 
-  [3/6] Building TypeScript...
-  ✔ TypeScript compiled successfully
+  ? How would you like to connect your Shopify app?
+    ❯ Create a new app — we'll guide you through it
+      I already have an app — enter my credentials
 
-  [4/6] Setting up Firebase...
-  ✔ Firebase project linked: my-app-12345
+  ℹ Opening Shopify Partner Dashboard...
 
-  [5/6] Checking Shopify CLI...
-  ✔ Shopify CLI detected
+  Follow these steps:
 
-  [6/6] Initializing git...
+    1. Sign in to your Partner account
+    2. Go to Apps → Create app → Create app manually
+    3. Enter app name: My App
+    4. Copy the Client ID and Client Secret
+
+  ? Paste your Client ID (API Key): abc123...
+  ? Paste your Client Secret: ********
+  ? What API access does your app need?
+    ❯ Read products            read_products
+      Read + write products    read_products,write_products
+      Orders + products        read_products,write_products,read_orders,write_orders
+      Custom scopes — enter manually
+
+  === Firebase Setup ===
+
+  ℹ Fetching your Firebase projects...
+  ? Select a Firebase project
+    ❯ [create a new project]
+      My Project (my-project-123)
+      Another Project (another-456)
+      [enter project ID manually]
+
+  === Setting Up ===
+
+  ℹ Scaffolding project...
+  ✔ Created 27 files in my-app/
+  ℹ Installing dependencies...
+  ✔ Dependencies installed
+  ℹ Building TypeScript...
+  ✔ TypeScript compiled successfully
+  ℹ Setting up Firebase...
+  ✔ Firebase project linked + Firestore provisioned
+  ℹ Checking Shopify CLI...
+  ✔ Shopify CLI detected
+  ℹ Initializing git...
   ✔ Git repository initialized with first commit
 
-  SUCCESS   Your Shopify + Firebase app is ready!
+  ✔  All done! Your Shopify + Firebase app is ready.
 
   Next steps:
 
@@ -98,6 +138,8 @@ The interactive CLI asks for your credentials and does the rest:
     firebase deploy
 ```
 
+No need to visit Firebase Console or Shopify Partner Dashboard beforehand — the CLI guides you through everything.
+
 ### 4. Deploy & Install
 
 ```bash

package/lib/index.js

@@ -37,10 +37,11 @@ const c = {
 const ok = (msg) => console.log(`  ${c.green}✔${c.reset} ${msg}`);
 const warn = (msg) => console.log(`  ${c.yellow}⚠${c.reset} ${msg}`);
 const info = (msg) => console.log(`  ${c.cyan}ℹ${c.reset} ${msg}`);
-const step = (n, total, msg) =>
-  console.log(
-    `\n  ${c.dim}[${n}/${total}]${c.reset} ${c.bold}${msg}${c.reset}`,
-  );
+const section = (title) => {
+  console.log();
+  console.log(`  ${c.cyan}===${c.reset} ${c.bold}${title}${c.reset} ${c.cyan}===${c.reset}`);
+  console.log();
+};
 
 // ─── Check if a CLI tool is available ────────────────────────────────────
 function hasCommand(cmd) {
@@ -95,6 +96,48 @@ function parseArgs(argv) {
   return { projectName, ...args };
 }
 
+// ─── Open URL in browser (cross-platform) ───────────────────────────────
+function openBrowser(url) {
+  const platform = process.platform;
+  try {
+    if (platform === "win32") execSync(`start "" "${url}"`, { stdio: "ignore" });
+    else if (platform === "darwin") execSync(`open "${url}"`, { stdio: "ignore" });
+    else execSync(`xdg-open "${url}"`, { stdio: "ignore" });
+  } catch {
+    info(`Open this URL in your browser: ${url}`);
+  }
+}
+
+// ─── List Firebase projects ──────────────────────────────────────────────
+function listFirebaseProjects() {
+  try {
+    const output = execSync("firebase projects:list --json", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const data = JSON.parse(output);
+    if (data.status === "success" && Array.isArray(data.result)) {
+      return data.result
+        .filter((p) => p.projectId)
+        .map((p) => ({
+          projectId: p.projectId,
+          displayName: p.displayName || p.projectId,
+        }));
+    }
+  } catch {}
+  return [];
+}
+
+// ─── Create Firebase project ─────────────────────────────────────────────
+async function createFirebaseProject(projectId, displayName) {
+  try {
+    await exec(`firebase projects:create "${projectId}" --display-name "${displayName}"`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ─── Interactive prompts ─────────────────────────────────────────────────
 async function getConfig(args) {
   // Check if running non-interactively
@@ -113,16 +156,22 @@ async function getConfig(args) {
     };
   }
 
+  const onCancel = () => {
+    console.log("\n  Cancelled.\n");
+    process.exit(0);
+  };
+
+  // ── Banner ────────────────────────────────────────────────────────
   console.log();
-  console.log(
-    `  ${c.bgGreen}${c.white}${c.bold} SHOPIFY + FIREBASE ${c.reset}  Create a new Shopify app`,
-  );
-  console.log();
+  console.log(`  ${c.green}${c.bold}🛍️  +  🔥${c.reset}  ${c.bold}create-shopify-firebase-app${c.reset}`);
+  console.log(`  ${c.dim}Serverless Shopify apps — free until you scale${c.reset}`);
 
-  const questions = [];
+  // ═══════════════════════════════════════════════════════════════════
+  section("App Configuration");
 
-  if (!args.projectName) {
-    questions.push({
+  let projectName = args.projectName;
+  if (!projectName) {
+    const res = await prompts({
       type: "text",
       name: "projectName",
       message: "Project directory name",
@@ -132,58 +181,225 @@ async function getConfig(args) {
         if (/[^a-zA-Z0-9._-]/.test(v)) return "Use only letters, numbers, dots, hyphens, underscores";
         return true;
       },
-    });
+    }, { onCancel });
+    projectName = res.projectName;
   }
 
-  questions.push(
-    {
-      type: "text",
-      name: "appName",
-      message: "App name (shown in Shopify admin)",
-      initial: args.projectName || "My Shopify App",
-    },
-    {
-      type: "text",
-      name: "apiKey",
-      message: `Shopify API Key ${c.dim}(Partner Dashboard → App → Client ID)${c.reset}`,
-      validate: (v) => (v.trim() ? true : "Required — get it from partners.shopify.com"),
-    },
-    {
-      type: "password",
-      name: "apiSecret",
-      message: "Shopify API Secret",
-      validate: (v) => (v.trim() ? true : "Required"),
-    },
-    {
+  const { appName } = await prompts({
+    type: "text",
+    name: "appName",
+    message: "App name (shown in Shopify admin)",
+    initial: projectName || "My Shopify App",
+  }, { onCancel });
+
+  const { appType } = await prompts({
+    type: "select",
+    name: "appType",
+    message: "What kind of app are you building?",
+    choices: [
+      { title: "Public app — list on the Shopify App Store", value: "public" },
+      { title: "Custom app — built for a single store", value: "custom" },
+    ],
+  }, { onCancel });
+
+  // ═══════════════════════════════════════════════════════════════════
+  section("Shopify Setup");
+
+  const { shopifySetup } = await prompts({
+    type: "select",
+    name: "shopifySetup",
+    message: "How would you like to connect your Shopify app?",
+    choices: [
+      { title: "Create a new app — we'll guide you through it", value: "create" },
+      { title: "I already have an app — enter my credentials", value: "existing" },
+    ],
+  }, { onCancel });
+
+  let apiKey, apiSecret;
+
+  if (shopifySetup === "create") {
+    console.log();
+    info("Opening Shopify Partner Dashboard...");
+    console.log();
+    console.log(`  ${c.dim}Follow these steps:${c.reset}`);
+    console.log();
+    console.log(`    ${c.cyan}1.${c.reset} Sign in to your Partner account`);
+    console.log(`    ${c.cyan}2.${c.reset} Go to ${c.bold}Apps${c.reset} → ${c.bold}Create app${c.reset} → ${c.bold}Create app manually${c.reset}`);
+    console.log(`    ${c.cyan}3.${c.reset} Enter app name: ${c.cyan}${appName}${c.reset}`);
+    console.log(`    ${c.cyan}4.${c.reset} Copy the ${c.bold}Client ID${c.reset} and ${c.bold}Client Secret${c.reset}`);
+    console.log();
+    openBrowser("https://partners.shopify.com");
+
+    const creds = await prompts([
+      {
+        type: "text",
+        name: "apiKey",
+        message: `Paste your Client ID (API Key)`,
+        validate: (v) => (v.trim() ? true : "Required — copy from the app you just created"),
+      },
+      {
+        type: "password",
+        name: "apiSecret",
+        message: "Paste your Client Secret (API Secret)",
+        validate: (v) => (v.trim() ? true : "Required"),
+      },
+    ], { onCancel });
+    apiKey = creds.apiKey;
+    apiSecret = creds.apiSecret;
+  } else {
+    const creds = await prompts([
+      {
+        type: "text",
+        name: "apiKey",
+        message: `Shopify API Key ${c.dim}(Client ID)${c.reset}`,
+        validate: (v) => (v.trim() ? true : "Required"),
+      },
+      {
+        type: "password",
+        name: "apiSecret",
+        message: "Shopify API Secret",
+        validate: (v) => (v.trim() ? true : "Required"),
+      },
+    ], { onCancel });
+    apiKey = creds.apiKey;
+    apiSecret = creds.apiSecret;
+  }
+
+  // Scope presets (like Shopify CLI template selection)
+  const { scopeChoice } = await prompts({
+    type: "select",
+    name: "scopeChoice",
+    message: "What API access does your app need?",
+    choices: [
+      { title: `Read products            ${c.dim}read_products${c.reset}`, value: "read_products" },
+      { title: `Read + write products    ${c.dim}read_products,write_products${c.reset}`, value: "read_products,write_products" },
+      { title: `Orders + products        ${c.dim}read_products,write_products,read_orders,write_orders${c.reset}`, value: "read_products,write_products,read_orders,write_orders" },
+      { title: "Custom scopes — enter manually", value: "__custom__" },
+    ],
+  }, { onCancel });
+
+  let scopes;
+  if (scopeChoice === "__custom__") {
+    const res = await prompts({
       type: "text",
       name: "scopes",
-      message: "API Scopes",
+      message: "Enter scopes (comma-separated)",
       initial: "read_products",
-    },
-    {
-      type: "text",
-      name: "projectId",
-      message: `Firebase Project ID ${c.dim}(Firebase Console → Project Settings)${c.reset}`,
-      validate: (v) => (v.trim() ? true : "Required — create one at console.firebase.google.com"),
-    },
-  );
-
-  const onCancel = () => {
-    console.log("\n  Cancelled.\n");
-    process.exit(0);
-  };
+      validate: (v) => (v.trim() ? true : "At least one scope is required"),
+    }, { onCancel });
+    scopes = res.scopes;
+  } else {
+    scopes = scopeChoice;
+  }
 
-  const answers = await prompts(questions, { onCancel });
+  // ═══════════════════════════════════════════════════════════════════
+  section("Firebase Setup");
+
+  let projectId;
+  const hasFirebase = hasCommand("firebase");
+
+  if (hasFirebase) {
+    info("Fetching your Firebase projects...");
+
+    const choices = [
+      { title: `${c.cyan}[create a new project]${c.reset}`, value: "__create__" },
+    ];
+    const projects = listFirebaseProjects();
+    if (projects.length > 0) {
+      for (const p of projects) {
+        choices.push({
+          title: `${p.displayName} ${c.dim}(${p.projectId})${c.reset}`,
+          value: p.projectId,
+        });
+      }
+    }
+    choices.push({ title: `${c.dim}[enter project ID manually]${c.reset}`, value: "__manual__" });
+
+    const { firebaseChoice } = await prompts({
+      type: "select",
+      name: "firebaseChoice",
+      message: "Select a Firebase project",
+      choices,
+    }, { onCancel });
+
+    if (firebaseChoice === "__create__") {
+      const { newProjectId } = await prompts({
+        type: "text",
+        name: "newProjectId",
+        message: "New project ID",
+        initial: projectName,
+        validate: (v) => {
+          if (!v.trim()) return "Required";
+          if (!/^[a-z0-9][a-z0-9-]*$/.test(v)) return "Only lowercase letters, numbers, and hyphens";
+          if (v.length < 6 || v.length > 30) return "Must be 6-30 characters";
+          return true;
+        },
+      }, { onCancel });
+
+      info(`Creating Firebase project: ${c.cyan}${newProjectId}${c.reset}...`);
+      const created = await createFirebaseProject(newProjectId, appName);
+      if (created) {
+        ok(`Project created: ${c.cyan}${newProjectId}${c.reset}`);
+        projectId = newProjectId;
+      } else {
+        warn("Could not create project automatically");
+        info("Create one at https://console.firebase.google.com");
+        const { manualId } = await prompts({
+          type: "text",
+          name: "manualId",
+          message: "Firebase Project ID",
+          validate: (v) => (v.trim() ? true : "Required"),
+        }, { onCancel });
+        projectId = manualId;
+      }
+    } else if (firebaseChoice === "__manual__") {
+      const { manualId } = await prompts({
+        type: "text",
+        name: "manualId",
+        message: "Firebase Project ID",
+        validate: (v) => (v.trim() ? true : "Required"),
+      }, { onCancel });
+      projectId = manualId;
+    } else {
+      projectId = firebaseChoice;
+      ok(`Using project: ${c.cyan}${projectId}${c.reset}`);
+    }
+  } else {
+    // No Firebase CLI — manual setup
+    const { firebaseSetup } = await prompts({
+      type: "select",
+      name: "firebaseSetup",
+      message: "How would you like to set up Firebase?",
+      choices: [
+        { title: "Create a new project — opens Firebase Console", value: "create" },
+        { title: "Enter project ID manually", value: "manual" },
+      ],
+    }, { onCancel });
+
+    if (firebaseSetup === "create") {
+      console.log();
+      info("Opening Firebase Console...");
+      info("Create a new project and note the Project ID");
+      console.log();
+      openBrowser("https://console.firebase.google.com");
+    }
 
-  const projectName = args.projectName || answers.projectName;
-  const projectId = answers.projectId;
+    const { manualId } = await prompts({
+      type: "text",
+      name: "manualId",
+      message: "Firebase Project ID",
+      validate: (v) => (v.trim() ? true : "Required"),
+    }, { onCancel });
+    projectId = manualId;
+  }
 
   return {
     projectName,
-    appName: answers.appName || projectName,
-    apiKey: answers.apiKey,
-    apiSecret: answers.apiSecret,
-    scopes: answers.scopes || "read_products",
+    appName: appName || projectName,
+    appType,
+    apiKey,
+    apiSecret,
+    scopes: scopes || "read_products",
     projectId,
     appUrl: `https://${projectId}.web.app`,
   };
@@ -326,15 +542,14 @@ export async function run(argv) {
     fs.rmSync(outputDir, { recursive: true, force: true });
   }
 
-  const totalSteps = 6;
+  // ═══════════════════════════════════════════════════════════════════
+  section("Setting Up");
 
-  // ── Step 1: Scaffold ──────────────────────────────────────────────
-  step(1, totalSteps, "Scaffolding project...");
+  info("Scaffolding project...");
   const fileCount = scaffold(outputDir, config);
   ok(`Created ${fileCount} files in ${c.cyan}${config.projectName}/${c.reset}`);
 
-  // ── Step 2: Install dependencies ──────────────────────────────────
-  step(2, totalSteps, "Installing dependencies...");
+  info("Installing dependencies...");
   const functionsDir = path.join(outputDir, "functions");
   try {
     await exec("npm install", functionsDir);
@@ -343,8 +558,7 @@ export async function run(argv) {
     warn(`npm install failed — run manually: cd ${config.projectName}/functions && npm install`);
   }
 
-  // ── Step 3: Build TypeScript ──────────────────────────────────────
-  step(3, totalSteps, "Building TypeScript...");
+  info("Building TypeScript...");
   try {
     await exec("npm run build", functionsDir);
     ok("TypeScript compiled successfully");
@@ -352,8 +566,7 @@ export async function run(argv) {
     warn("Build failed — run manually: cd functions && npm run build");
   }
 
-  // ── Step 4: Firebase CLI ─────────────────────────────────────────────
-  step(4, totalSteps, "Setting up Firebase...");
+  info("Setting up Firebase...");
   if (!hasCommand("firebase")) {
     info("Firebase CLI not found — installing globally...");
     try {
@@ -375,10 +588,9 @@ export async function run(argv) {
     });
   }
 
-  // ── Step 5: Shopify CLI ─────────────────────────────────────────────
-  step(5, totalSteps, "Checking Shopify CLI...");
+  info("Checking Shopify CLI...");
   if (hasCommand("shopify")) {
-    ok("Shopify CLI detected — you can use `shopify app dev` for local development");
+    ok("Shopify CLI detected");
   } else {
     info("Shopify CLI not found — installing globally...");
     try {
@@ -387,12 +599,10 @@ export async function run(argv) {
     } catch (e) {
       warn("Could not install Shopify CLI automatically");
       info("Install manually: npm i -g @shopify/cli");
-      info("Optional — you can also develop with Firebase emulators");
     }
   }
 
-  // ── Step 6: Initialize git ────────────────────────────────────────
-  step(6, totalSteps, "Initializing git...");
+  info("Initializing git...");
   if (hasCommand("git")) {
     try {
       await exec("git init", outputDir);
@@ -403,43 +613,35 @@ export async function run(argv) {
       warn("Git init failed — initialize manually if needed");
     }
   } else {
-    warn("Git not found — skipping repository initialization");
+    warn("Git not found — skipping");
   }
 
-  // ── Done! ─────────────────────────────────────────────────────────
   printSuccess(config);
 }
 
 // ─── Success output ──────────────────────────────────────────────────────
 function printSuccess(config) {
   console.log();
-  console.log(
-    `  ${c.bgGreen}${c.white}${c.bold} SUCCESS ${c.reset}  Your Shopify + Firebase app is ready!`,
-  );
+  console.log(`  ${c.green}${c.bold}✔  All done!${c.reset} Your Shopify + Firebase app is ready.`);
   console.log();
   console.log(`  ${c.bold}Next steps:${c.reset}`);
   console.log();
   console.log(`    ${c.cyan}cd ${config.projectName}${c.reset}`);
   console.log(`    ${c.cyan}firebase deploy${c.reset}`);
   console.log();
-  console.log(`  ${c.bold}Then install on your dev store:${c.reset}`);
+  console.log(`  ${c.bold}Install on your dev store:${c.reset}`);
   console.log();
-  console.log(
-    `    ${c.cyan}${config.appUrl}/auth?shop=YOUR-STORE.myshopify.com${c.reset}`,
-  );
+  console.log(`    ${c.cyan}${config.appUrl}/auth?shop=YOUR-STORE.myshopify.com${c.reset}`);
   console.log();
-  console.log(`  ${c.bold}Or use Shopify CLI for local development:${c.reset}`);
+  console.log(`  ${c.bold}Or develop locally:${c.reset}`);
   console.log();
   console.log(`    ${c.cyan}shopify app dev${c.reset}`);
   console.log();
   console.log(`  ${c.dim}─────────────────────────────────────────${c.reset}`);
-  console.log();
   console.log(`  ${c.dim}App URL:       ${config.appUrl}${c.reset}`);
   console.log(`  ${c.dim}Firebase:      ${config.projectId}${c.reset}`);
   console.log(`  ${c.dim}Scopes:        ${config.scopes}${c.reset}`);
   console.log();
-  console.log(`  ${c.dim}Docs: https://github.com/mksd0398/create-shopify-firebase-app${c.reset}`);
-  console.log();
 }
 
 // ─── Help output ─────────────────────────────────────────────────────────

package/package.json

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