Keep core untouched
Your app never edits an Arc CMS (core) file, so every Arc CMS update merges cleanly. One command tells you whether that still holds; run it before every commit.
Before every commit
npm run check:coreIt compares your working copy, committed or not, new files included, with the Arc CMS version your app is based on, and sorts every difference:
| Kind | Files | Result |
|---|---|---|
| custom | src/custom/, functions/src/custom/, firestore.app.rules, storage.app.rules, firestore.app.indexes.json, tests/rules/custom/, docs/custom/, custom/, .github/ (CI workflows) | Fine: counted, not listed |
| install | src/environments/environment.ts, src/environments/environment.prod.ts, src/environments/arc-install.ts, src/environments/firebase-web.<projectId>.ts | Fine: this install's own settings |
| review | package.json, package-lock.json, functions/package.json, functions/package-lock.json | Allowed, but listed: worth a look before the next update |
| core | Everything else | Listed, and the check fails |
| Exit code | When |
|---|---|
| 0 | No core file changed. Also in the Arc CMS repository itself, which has no core to protect. |
| 1 | A core file changed, or there is no Arc CMS version to compare with |
Because a failure exits with 1, the same command works as a CI step.
The upstream remote
The check compares with Arc CMS from a remote named upstream. Without it the check checks nothing and fails, so it can never pass by accident. Add it once:
git remote add upstream git@github.com:quadralyst/arccms.gitgit fetch upstreamIt compares with the Arc CMS branch your copy follows: of upstream/main and upstream/dev, the one your work is fewest commits ahead of, which is the one you copied or last merged. A copy taken from dev needs nothing extra. The first line of the report names the branch it chose. To choose yourself, name the branch:
npm run check:core -- --against upstream/devMoving a core file into the custom space still counts as a core change: the check looks at the old path too. Copying a core component into src/custom/ and editing the copy passes the check, but your app then misses every later fix to it. Use the component as it is, and ask for an option instead (below).
When the check lists a core file
Undo the edit to the core file, then put the change where it belongs:
| You changed | Put it in |
|---|---|
| A page or a route | src/custom/pages/ or src/custom/routes.ts: Add pages and routes |
| The admin menu or the member menu | src/custom/nav.ts (your items) and src/custom/nav-changes.ts (changes to Arc CMS's): Change the admin menu, Change the member menu |
| Where people land, or the member dashboard | src/custom/home.ts, src/custom/user-dashboard.ts: Build the member area |
| Wording or translations | src/custom/i18n/, which can also reword core text |
| Styles | src/custom/styles.css, loaded after every core stylesheet |
| Features on or off | src/custom/features.ts: Choose your app's features |
The home page, a content template, the site header or footer, the sign-in page's brand panel, a static page, the site's styles, favicon or error pages (anything in public/_site/ or public/) | src/custom/site/, at the same path: Design templates. When the check lists files in public/, it points to npm run arc:own-site, which moves them for you: Move your site into src/custom/site |
| A Cloud Function or trigger | functions/src/custom/index.ts: Write your own Cloud Functions |
| A command-line script, its data, or design files | custom/: Run scripts and keep data |
| Security rules or indexes | firestore.app.rules, storage.app.rules, firestore.app.indexes.json: Set security rules and indexes |
The full list of places your app owns is in Use the custom space.
If none of them can do it, the custom space is missing a plug point or a component is missing an option. That change belongs in Arc CMS as a general feature that any app can use: make it there (see Keep core generic), then pull it into your app with the next update. Until then, keep the app's version out of core.
Take Arc CMS updates
With the check passing, an update is a merge of the newer Arc CMS into your repository, followed by installs, tests and a deploy. The steps, and what to do when the merge conflicts, are in Upgrade Arc CMS. Your custom files never conflict: Arc CMS ships them once, empty, and never changes them again. The install files (environment.ts, environment.prod.ts, arc-install.ts) ship with no Firebase project, and Arc CMS never changes their values either; when it adds a key to one, CHANGELOG.md names it (see Before the first npm run dev).
npm run arc:upgrade is not part of a routine update. It moves a project whose Arc CMS functions are still deployed under their plain names to the arccms- names, once; Upgrade Arc CMS covers when and how.