Dev, staging and production

An app usually needs several Firebase projects: one to develop on, one to test a release on, one for real users. Each has its own web settings, and every build, deploy and script picks the project the same way: by its .firebaserc alias or its id.

How a build knows its project

A build gets the Firebase project it talks to from ARC_PROJECT. npm run deploy sets it to the project it is deploying to, so a deploy always builds the site for that project, and a site can never go out talking to another one. For that project, the build uses:

1. src/environments/firebase-web.<projectId>.ts, the project's own web settings, when you have fetched them (below);
2. otherwise the environment file you edited by hand: environment.prod.ts for the production alias, environment.ts for any other, only if it names that very project. If it names another, the build stops and prints the command that fixes it.

With no ARC_PROJECT, npm run dev and npm run build use the project of the default alias in .firebaserc when arc:configure has written its firebase-web.<projectId>.ts. Only when there is no such file do they fall back to the environment file: environment.ts for npm run dev, environment.prod.ts for npm run build (or environment.ts with USE_DEV_ENV=true). Either way they print the project and the file as they start, such as Firebase project: acme-dev (the default alias, environments/firebase-web.acme-dev.ts).

Before the first npm run dev

Arc CMS ships environment.ts, environment.prod.ts and arc-install.ts with no Firebase project in them. A copy that has not been set up stops at start with "No Firebase project configured: run npm run arc:configure", rather than talking to a project that is not yours, where a test sign-up or write would land somewhere you may not be able to clean up. So before the first npm run dev, either give your development project the default alias and fetch its settings:

firebase use --add
npm run arc:configure -- --project=default --web-config=fetch

or fill in environment.ts (and environment.prod.ts) by hand.

Every part of the app gets the chosen file, wherever it imports src/environments/environment.ts from: the build swaps the file the import leads to, not the words of the import (environmentSwap in scripts/arc-environment.mjs). A test builds a small app with shallow, deep and barrel imports and fails if any of them keeps another project's settings.

Add a project

1. Give it an alias in the Firebase CLI:

   firebase use --add

   Choose the project and call it, for example, staging. This writes .firebaserc, which git ignores.

2. Fetch its web settings:

   npm run arc:configure -- --project=staging --web-config=fetch

   The Firebase CLI reads the project's web app settings. They are stored in arccms.config.json under projects.<id>.firebaseConfig and written to src/environments/firebase-web.<id>.ts, which you commit. If the project has several web apps, the one an environment file already names is used; otherwise the command lists them and asks for --web-app=<appId>. Without the CLI, save the settings the Firebase console shows (Project settings, Your apps) to a file and pass --web-config=<file>; JSON, the console's snippet and an environment file (such as the committed firebase-web.<id>.ts) all work.

3. Set it up like any project, with the other arc:configure flags if it needs its own database, bucket or site (see Configure a project).

4. Deploy it:

   npm run deploy -- --project=staging

   This builds the website with staging's settings and the functions, then deploys. To deploy from CI instead, see Deploy from CI. The guided npm run deploy offers every alias. Then publish its static pages:

   npm run seed -- staging

Build without deploying

npm run build:project -- --project=staging

The same as ARC_PROJECT=staging npm run build, on every operating system. The build prints the project and the file it used. ARC_PROJECT works with npm run dev too, to run the app against another project on your machine.

Build like production

A project's build mode says how a build for it runs. production builds the site as your users get it: Angular's production mode, no debug mode, no missing-translation warnings in the console, and no instance label (the project and database) on the sign-in page. development keeps all of those, so you always know which project you are signed in to.

By default a project marked production (below) builds as production and every other project as development, as builds always ran. To rehearse a release on staging exactly as it will run live, build staging like production:

npm run arc:configure -- --project=staging --build-mode=production

This is not the production guard: staging still deploys without typing its id back. The build mode applies to a project with its own web settings (fetched above); the guided deploy shows it in the summary as Build:.

The generated firebase-web.<id>.ts imports environment.ts and sets only production, firebaseConfig and the project's install settings (arcInstall, the same as its entry in arc-install.ts, which wins), so every other key you add to environment.ts reaches every project's build, with no need to configure again. Keep a key that differs per project out of environment.ts: put it in arccms.config.json or read it at run time.

Guard production

Mark any project as production, whatever its alias is called:

npm run arc:configure -- --project=live --production=yes

The guided deploy then asks you to type the project id back before it deploys there, admin scripts print (production) next to the project, and its builds run like production unless you set --build-mode=development. The production alias and ids that say prod or live are guarded as before.

A deploy with options, such as one from a script or CI, deploys a marked project only with its id given back, --confirm-production=<project id>; without it a terminal asks for the id and anywhere else the deploy stops (see Deploy from CI). Projects that are not marked need nothing.

Scripts take the same project

Troubleshooting