Use the custom space

All of your app's code goes in a handful of files and folders that Arc CMS ships once, empty, and never changes again. This page lists each one, what it is for, and where Arc CMS reads it.

The files

In the browser app, src/custom/:

In the Cloud Functions, functions/src/custom/:

At the root and in the test and docs folders. Arc CMS ships nothing in these beyond a README; you create the files when you need them:

Where Arc CMS reads each file

Each custom file has one plug point: a place in core that reads it. You never edit these core files; they are listed so you know what happens to your code.

Styles and translations

Put global styles in src/custom/styles.css. Styles for one page belong in that page's component. Styles for the public website (header, footer, templates) go in src/custom/site/site.css, and the words of the website's templates in src/custom/site/strings/ (see Publish in more than one language).

Add the app's words to src/custom/i18n/en.json under a custom key. A key that already exists in core is reworded for the whole admin:

{
  "custom": { "nav": { "lessons": "Lessons" } },
  "admin": { "nav": { "users": "Parents" } }
}

The admin has two languages, English and Hindi, and each reads its own file in src/custom/i18n/. Put the words an admin sees in src/custom/i18n/hi.json too. The test suite checks the ones it can tell are admin words, the labels of your admin menu items and admin menu changes and the core admin words you reword, and that hi.json has no key en.json lacks. It also fails on a menu labelKey, admin or member, that no English file has. Words only members see need Hindi only when you offer Hindi to members; anything missing shows in English. See Languages. For a language your members use and the admin does not, such as German, declare it in src/custom/languages.ts and write src/custom/i18n/de.json: see Member languages.

Use core building blocks

The rule forbids editing core files, not using them. Your pages import core components the same way core pages do and get every later fix for free. These are meant for apps:

If a building block falls short, the missing option is added to it in Arc CMS. Copying the component into the custom space loses every later fix.

Why updates never conflict

• Arc CMS ships each file in src/custom/, functions/src/custom/, docs/custom/ and custom/ once (empty, or a README) and never changes or deletes it again: not its code, not its comment, not a README row. So a merge never touches a file you own, whatever you rewrote in it.
• A new plug point comes as a new file, shipped empty, never as a new export in a file you already have. A new file merges on its own. Its comment links the page that explains it; examples live in the docs, not in your files.
• The README in src/custom/ is never changed again either, so its table may miss newer files, such as nav-changes.ts, and its line about a file gaining a new export no longer holds. This page is the full, current list, and the rule.
• The app's rules, indexes, rules tests and docs are files Arc CMS does not ship at all.
• Everything built from your choices (the combined rules in .arc-build/ and the functions' feature files) is generated and ignored by git.

npm run check:core sorts every file you changed into the custom space (fine), install settings such as src/environments/environment.ts and src/environments/arc-install.ts (fine), dependency lists such as package.json (fine, worth a look), and core (a problem). See Keep core untouched.

In Arc CMS itself, src/app/custom-space.spec.ts holds Arc CMS to this: it fails when a file it shipped in the custom space changed or was deleted, against the hashes in SHIPPED_FILES in scripts/custom-starters.mjs. It is skipped in your app, where the files are yours to change.