shopify-firebase-app – DevOps & Infrastructure skill for AI agents

Shopify Apps on Firebase, with Nitrogen

Overview

Nitrogen (npx @mksd0398/nitrogen) scaffolds a Shopify embedded app on Firebase. It has one Cloud Function (gen 2, Node.js 24) per API resource, in TypeScript or JavaScript, plus Firestore, Hosting and Secret Manager. Its pages are plain HTML built from Polaris web components and App Bridge, with no build step. An app is single- or multi-tenant, and every generated project has a test suite.

Two rules come before anything else:

• Working inside an app? Read its AGENTS.md first; it is the project's own guide. Apps made before Nitrogen 3.4 have none, so read [references/app-guide.md](references/app-guide.md) instead. It is the same guide, written for TypeScript; a JavaScript app has .js files.
• Building UI? Use [references/polaris.md](references/polaris.md) for every Polaris web component, and [references/app-bridge.md](references/app-bridge.md) for the shopify global. Never use Polaris React or @shopify/app-bridge-react.

Adapted from the [upstream skill](https://github.com/mksd0398/nitrogen/tree/master/skills/shopify-firebase-app) (MIT). Nitrogen is an independent project, not affiliated with or endorsed by Shopify or Google.

When to Use This Skill

• Use when someone wants a Shopify app on Firebase (Cloud Functions, Firestore, Hosting), or a Shopify app without Remix, React Router or a server.
• Use when they mention Nitrogen or npx @mksd0398/nitrogen.
• Use when working in a Nitrogen project, recognisable by functions/src/api/, web/*.html pages with <s-app-nav>, and an AGENTS.md that names Nitrogen.
• Use it to create such an app, to add APIs, webhooks, pages, scopes or Firestore data to one, and to deploy it.
• Do not use it for Shopify apps built on Remix or React Router, such as those from shopify app init.

How It Works

Step 1: Get what only the user can give

Inspect existing authorized project configuration and account context first. Ask only for missing decisions; never invent identifiers or request secrets in chat.

| You need | Where the user finds it |

|---|---|

| Shopify client ID and secret | The app's settings in the Shopify Dev Dashboard. Create the app there first if it does not exist. |

| A Firebase project ID | An existing project, or a new id (6 to 30 characters: lowercase letters, digits, hyphens) for you to create with --create-project. |

| The Blaze plan on that project | https://console.firebase.google.com/project/PROJECT_ID/usage/details. Functions and Secret Manager need it. It is pay as you go, with a free monthly allowance. |

| One store, or any store | One store makes it single-tenant (--shop=STORE.myshopify.com). Any store makes it multi-tenant (leave --shop out). |

| Where the data lives | A Firestore location such as us-central1 or europe-west1. It cannot be changed later, so ask. |

Choose the scopes from the feature yourself. Keep read_products only if the requested starter/product UI actually needs it; remove unused starter pages instead of retaining unnecessary access, and add what the feature needs: orders need read_orders, and so on. Add write_ scopes only for what the app changes.

Use the host's approved interactive authentication flow for: firebase login now, and shopify auth login before the first shopify app deploy.

Ask the user to save the client secret to secret.txt in the folder you will run the CLI from, which is outside the app. Do not ask them to paste it into the chat, and never print it. Once it is stored in Secret Manager, they can delete the file.

Step 2: Scaffold

The scaffolder is third-party executable code with package-install, cloud-provisioning and Git-commit effects. Review the selected version and its dependency/lifecycle behavior before execution; use an isolated new project directory. --skip-provision is only a cloud-provisioning switch, not a sandbox or a guarantee of no local/network side effects. Do not run a provisioning path until the intended Firebase project, region, billing and resource effects are authorized. Store secret.txt outside Git/synced folders with owner-only permissions and no tracing; environment variables are not immune to child-process/log disclosure. Unset the secret after use and remove the temporary file once secure storage is verified.

There is no terminal to answer the wizard's questions in, so pass every answer as a flag:

IFS= read -r SHOPIFY_API_SECRET < secret.txt  # Private file; disable tracing; no newline in the value
export SHOPIFY_API_SECRET
npx "@mksd0398/nitrogen@${NITROGEN_VERSION:?Set the approved reviewed version}" my-app \
  --api-key=CLIENT_ID \
  --project-id=PROJECT_ID \
  --firestore-region=us-central1 \
  --scopes=read_products,read_orders

| Flag | Use it when |

|---|---|

| --create-project | The Firebase project does not exist yet. |

| --shop=STORE.myshopify.com | The app is for one store. |

| --language=javascript | The user wants JavaScript. TypeScript is the default. |

| --region=REGION | The functions should run somewhere other than next to Firestore. |

| --overwrite | my-app exists and the user said to replace it. |

| --skip-provision | A trial run that touches nothing in Firebase. For a real app, leave it out. |

Run it from the parent folder; it creates my-app/. It stops with exit code 1 when a flag is missing or the folder already has files, and says why. It never replaces the folder it runs from. --no-deploy and --skip-shopify belong to the interactive wizard and do nothing here.

What it does: it creates Firestore and a Firebase web app (both only with --firestore-region), stores the secret in Secret Manager, installs dependencies, builds, runs git init and commits. It does not deploy, and "All done" means the scaffold is done.

Read its output for these warnings. Run the commands from inside my-app.

• "Firebase project … not found in your account". Either the project does not exist, so ask the user whether to create it (firebase projects:create PROJECT_ID --display-name "App name"), or they are signed in to another Google account (firebase login:list). Then set up Firebase by hand, as below.
• "This project is on the Spark (free) plan". The user upgrades to Blaze. Then store the secret: firebase functions:secrets:set SHOPIFY_API_SECRET --data-file=../secret.txt --project=PROJECT_ID.
• "Could not store the Client Secret". Run that same command once the project is on Blaze.

When the setup was skipped, or stopped early, finish it by hand:

firebase firestore:databases:create "(default)" --location=LOCATION --project=PROJECT_ID
firebase functions:secrets:set SHOPIFY_API_SECRET --data-file=../secret.txt --project=PROJECT_ID

Step 3: Deploy and install

cd my-app
cd functions && npm test && cd ..
firebase deploy --project PROJECT_ID
shopify app deploy

firebase deploy ships the functions, the pages and the Firestore rules. shopify app deploy sends shopify.app.toml to Shopify: the app URL, scopes and webhook subscriptions. The user then installs the app from the Dev Dashboard onto a development store. https://PROJECT_ID.web.app/auth?shop=STORE.myshopify.com also works.

Step 4: Change an app

Follow the app's AGENTS.md. These are the steps agents miss most:

• A new API needs its file in functions/src/api/, an export in functions/src/index, and two rewrites in firebase.json. The rewrites use the lowercase export name and the same region as the others. npm test fails if the three disagree.
• A new scope goes in shopify.app.toml and functions/.env, then needs shopify app deploy. Merchants approve it the next time they open the app.
• Orders and customers are protected customer data. The user selects the data the app uses in the Partner Dashboard, under the app's API access; apps made in the Dev Dashboard are listed there too. Until then, Shopify refuses order and customer webhooks, even on a development store.
• A new Firestore collection is keyed by tenantId(ctx.app, ctx.shop) and listed in TENANT_DOCS or TENANT_FIELD in functions/src/webhooks. That way shop/redact deletes it.
• A new page needs its link added to the <s-app-nav> of every page, because each page carries its own copy.
• A new webhook topic reaches the app only after shopify app deploy.

Run cd functions && npm test after every change, and before every deploy.

Examples

Example 1: A one-store JavaScript app on a new Firebase project

The user gave the client ID, a new project id, their store and the location europe-west1, and saved the secret to secret.txt. The feature reads orders.

IFS= read -r SHOPIFY_API_SECRET < secret.txt  # Private file; disable tracing; no newline in the value
export SHOPIFY_API_SECRET
npx "@mksd0398/nitrogen@${NITROGEN_VERSION:?Set the approved reviewed version}" my-app \
  --api-key=CLIENT_ID \
  --project-id=PROJECT_ID 

… (full content is in the download package)