Shopify Apps on Firebase, with Nitrogen

This skill guides embedded Shopify app development with Nitrogen on Firebase. The scaffold uses one generation-2 Cloud Function per API resource, Node.js 24, TypeScript by default or JavaScript, Firestore, Hosting, and Secret Manager. Pages use plain HTML, Polaris web components, and App Bridge without a frontend build step. Apps can serve one store or multiple tenants, and generated projects include tests. Nitrogen is independent of Shopify and Google.

For existing apps, read the project's AGENTS.md before changing it. Projects created before Nitrogen 3.4 use the bundled app-guide reference instead. UI work follows the Polaris web-component and App Bridge references; Polaris React and the React App Bridge package are excluded.

Use it to create a Firebase-backed Shopify app or extend a Nitrogen project with APIs, pages, webhooks, scopes, or Firestore collections. It is outside the architecture of Shopify apps generated with Remix or React Router. Inspect existing authorized configuration before asking for missing decisions. Never invent project identifiers or request secrets in conversation.

Setup needs a Shopify client ID and secret, Firebase project, tenancy choice, and Firestore location. Functions and Secret Manager require Blaze billing, which only the user can enable. Firestore location cannot be changed after creation. Choose minimal scopes from the feature: retain read_products only when the requested starter UI needs it, add read_orders for orders, and grant write scopes only for requested changes.

Use the host's supported authentication flow for Firebase and Shopify accounts. The client secret belongs in an owner-only private file outside Git and synced folders, then in Secret Manager; emulator use has an ignored local secret file. Avoid tracing and output, unset temporary secret variables, and remove the temporary file after secure storage is verified. Environment variables can still leak through children or logs.

The scaffolder is third-party executable code with installation, provisioning, and Git-commit effects. Review the approved pinned version and dependency behavior, then use an isolated new directory. Pass every required answer as a flag because the noninteractive path cannot answer wizard questions. Options cover project creation, single-store tenancy, JavaScript, function region, and authorized replacement of an existing output directory. The --skip-provision flag prevents Firebase provisioning but does not isolate local or network effects. Wizard-only no-deploy and skip-shopify switches have no effect here.

Scaffolding creates the app directory, installs dependencies, builds, initializes Git, and commits. With a Firestore region it can create Firestore and a Firebase web app, and it stores the secret in Secret Manager. It does not deploy. Missing flags or existing output files stop the command rather than replacing the current directory. If the project is absent or the wrong account is active, verify account context and obtain authorization for project creation. Billing or secret-storage warnings require completing that setup before deployment.

A new API needs a resource file, an index export, and two Hosting rewrites whose lowercase service name and region match the function. A mismatch can produce a Hosting 404; project tests check their agreement. Routes return JSON or throw HttpError. A new scope goes into both Shopify configuration and the functions environment configuration, then requires Shopify deployment and merchant approval.

New Firestore collections use tenantId(ctx.app, ctx.shop) and appear in TENANT_DOCS or TENANT_FIELD so shop/redact deletes tenant data. Use verified ctx.shop and ctx.app rather than request-supplied identity. Keep Firestore client rules denying access and reach it through functions. Missing signatures, session tokens, or bodies must be refused without loosening verification.

Every page maintains its own navigation copy, so add a new page link to each page. Webhook topics require a subscription, a matching handler, a function deployment, and Shopify configuration deployment. Handlers answer within five seconds. Orders and customers are protected customer data: the user must select the required data in the Partner Dashboard before Shopify accepts those webhooks, including on development stores.

Deployment separates application checks, Firebase resources, and Shopify configuration:

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

Firebase deployment ships functions, pages, and rules; Shopify deployment publishes app URL, scopes, and webhook subscriptions. Installation follows through the Dev Dashboard or the documented auth route. Run the app's tests after changes and before deployment, while recognizing that tests neither independently prove security properties nor authorize release.

Inspect actual generated code and dependencies. Check invalid, expired, and wrong-audience tokens; JWT signature, issuer, time claims, and tenant binding; raw-body webhook HMAC; replay handling; cross-tenant access; and redaction. Deny-client rules do not constrain Admin SDK access, and public invocation only permits reaching the verifier.

Confirm the target app, project, and store, inventory existing resources, and prefer scoped deployments. Avoid force flags that suppress deletion confirmation. Hosting ends rewritten requests after 60 seconds. For Google 403 responses, inspect invocation configuration and authentication before changing exposure. Newly enabled billing can temporarily produce 429 responses. Scope failures require inspecting approval and installation state rather than blindly deleting sessions.