Sharing a Firebase project
Arc CMS can run in a Firebase project that another app already uses, for example as the admin and content backend of a mobile app. It keeps its own database, functions, website and files, so neither app touches the other's. Sign-in stays shared.
Why share a project
Your app and Arc CMS then see the same sign-in accounts, and Arc CMS can read your app's users as an audience for email and lists (see App audience). Without that need, give Arc CMS a project of its own: nothing on this page applies.
What Arc CMS keeps apart
| Part | How it is kept apart |
|---|---|
| Firestore | A database of its own, named in the install settings (the setup suggests arccms). The other app keeps (default). Every function opens it through functions/src/init.ts, and every trigger listens on it through arcDocument(). Since Firebase takes one rules file per database, each app keeps its own rules and indexes. |
| Cloud Functions | Every Arc CMS function is named arccms- plus its name (functions/src/function-names.ts), and belongs to the arccms codebase in firebase.json. A deploy of one codebase never deletes the other's functions, and Arc CMS's deploy only ever compares its own. |
| Hosting | A hosting site of its own (the setup suggests the project id followed by -arccms), or no website at all. Arc CMS then never publishes to the project's main site. |
| Storage | A bucket of its own (the setup suggests the project id followed by -arccms) and an upload folder in it (arccms/). Firebase takes one storage rules file per bucket, so in the other app's bucket Arc CMS deploys no storage rules. |
| Claims | Arc CMS's custom claims are named arccms_role and arccms_uid, and it never reads a plain role claim. See Roles and claims. |
What stays shared
- Sign-in. A project has one Firebase Auth pool and one set of sign-in providers. The other app's users can reach Arc CMS's sign-in page; with no Arc CMS record they are told they have no access. Sign-ups turn off when the first-run setup finishes (admin-only sign-in, the default for a shared project), so admins add people under Users.
- Accounts in both apps. When an admin adds someone who already has an account from the other app, Arc CMS reuses the account and never changes it. Deleting that Arc CMS user removes only Arc CMS's record and claims, never the account. The person can still use Forgot password on Arc CMS's sign-in page: it is their one login, so the new password works in both apps. A login the other app owns outright, or one with no Arc CMS record, is told to reset its password in that app (see Forgot password).
- Custom claims on an account. Arc CMS merges its claims into the existing ones. Firebase has no atomic merge, so if both apps write claims on the same account at the same moment, one write can be lost. Arc CMS writes claims rarely (sign-up, a role change, blocking, deletion).
- The project itself: billing, quotas, and Google's per-minute limit on changes to functions.
How it is set up
The guided deploy asks, the first time it meets a project, whether the project is shared with another app, then suggests every name above. It writes the settings, prints the commands that create the database, the site and the bucket, and stops so you can run them. The steps are in Share a Firebase project.
The settings live per project in arccms.config.json (see arccms.config.example.json), with the profile backend. That profile refuses to deploy without its own database, hosting site (or none) and bucket. From the settings, npm run arc:configure writes the files each part reads: src/environments/arc-install.ts for the app (commit it), functions/.env.{projectId} for the functions and firebase.{projectId}.json for the Firebase CLI. See Architecture.
Traps
A Firebase deploy creates a missing named database by itself, in the project's default location, and so does firebase deploy --dry-run. Create the database first, with the command the setup prints: that is how you choose its location (the same as the other app's). Do not run a dry run to "check" a named-database config.
If the Arc CMS database is deleted and created again, the functions that trigger on it stay bound to the old one and never fire, so nothing that depends on them happens, publishing included. Updating the functions does not rebind them. Delete the arccms- Firestore trigger functions and deploy them again.
Plain firebase deploy uses firebase.json, which knows nothing of Arc CMS's database, site or bucket, so it would deploy Arc CMS's rules and website over the other app's. Always deploy with npm run deploy, which picks the project's generated config.