Primers

Concept-oriented overviews of how the major areas of this codebase hang together.

A primer doesn't tell you how to add a new thing (that's what the BUILDING_* how-to docs are for) and doesn't explain why one specific bit of code looks the way it does (that's tutorials). It gives you the lay of the land for an area, with links out to the deeper docs for each topic.

If you're new to the codebase, start here. If you've been here a while and someone asks "how does X work in our project", point them at the relevant primer.

What's here

  • Getting started primer — the on-ramp before any of the others are useful: what to install, the one-command quick start (node build.mjs), local secrets, the shape of the solution, and how to make your first contribution.
  • Frontend primer — the Vite-powered public-site frontend in UmbracoCommunity.StaticAssets. Covers the dual dev workflow, the manifest-driven Razor integration, the entrypoint convention, Lit + PostCSS, testing, and what builds for production. Backoffice frontends are signposted at the end.
  • Backend primer — the C# side in UmbracoCommunity.Web and UmbracoCommunity.Web.UI. Covers the request flow (URL → render controller → view model builder → view), the three controller flavours, the builder pattern and DI registration, bootstrapping through composers, output caching policies, and the self-contained Features/Sessionize/ module pattern.
  • Multi-tenancy primer — one Umbraco instance, several sites. The single invariant (scope every content lookup to the current request's tenant), the multi-root content tree, the GetSiteSettings() / AncestorOrSelf<T>() helpers, domain-binding for routing-level lookups with no current page, and the intentional cross-tenant exceptions. Threads together the multi-tenant tutorial suite.
  • Backoffice extensions primer — the four backoffice client codebases (UmbracoCommunity.Extensions, UmbracoCommunity.BlockRestrictions, Umbraco.Community.NotFoundTracker, UmbracoCommunity.BlogAnnouncements). Covers the App_Plugins umbraco-package.json manifest, the bundle pattern, how dashboards / property editors / workspace views register and scope themselves via conditions, the @umbraco-cms/backoffice design system and UMB_AUTH_CONTEXT, calling secured C# APIs with the user's bearer token, and why each client is its own library-mode Vite project.
  • Caching primer — the dozen scattered caches mapped to the four questions they answer (deploy-time artefacts, API responses, expensive cross-request compute, slow third-party data), which mechanism each uses (RuntimeCache, static IMemoryCache, OutputCache policies, two-tier IMemoryCache, stale-fallback feeds), and what invalidates each. Includes a lookup table and "which to reach for" guidance.
  • Third-party integrations primer — the external dependencies: three server-side data feeds (Sessionize, Calendar, Community Blogs) that all follow one resilient pattern (options + named HttpClient + cache-with-stale-fallback + composer), plus the avatar/build-time bits. Notes what isn't here (Matomo, Intercom, Maps, release tracking) so readers don't go hunting.
  • Content modelling primer — the three shapes a content type can take (document, element, settings), how compositions (ICompositionSeo, IContentBlockIntro, …) share fields across unrelated content types, how Models Builder turns backoffice configuration into generated C#, and the ModelTypeAlias convention. Threads together the Models/ folder structure and the BUILDING_PAGES.md / BUILDING_BLOCKS.md how-tos.
  • SEO and structured data primer — the pipeline from ICompositionSeo to rendered tags: SeoDataService assembling the view model, the three Schema.NET builders, OpenGraph/Twitter Cards and the Sessionize session deep-link override, canonical URLs and pagination, robots directives, and per-tenant sitemap generation.

Every primer in the original backlog has now been written — there's currently nothing planned.

Adding a new primer

A new primer earns its keep when an area of the codebase has:

  • More than one or two surface-level concepts a new contributor needs to hold in their head, and
  • A scattering of how-to / tutorial / reference docs that benefit from being threaded together.

If the answer fits in a paragraph in CLAUDE.md, it doesn't need a primer. If you find yourself writing the same "let me explain how X works in this project" thread three times, it does.

Start it directly in this folder as <topic>.md with a kebab-case filename and add it to What's here above in the same commit. If it's not ready to finish in one sitting, leave a > **Status:** Planned stub the way docs/tutorials/ does for its remaining stubs, rather than a separate backlog entry.

You don't need to maintain a contributors list by hand. Each rendered doc shows a Contributors section generated from git history (docs/contributors.generated.json, produced by npm run generate:doc-contributors and refreshed in CI). Open a PR and you'll be credited automatically — with your GitHub avatar where your commit email is linked to your account.

  • Backend primer

    The C# side of the site lives across five projects, with src/UmbracoCommunity.Web/ as the heart of it all — controllers, view model builders, services, view components, and the small ASP.NET integrations Umbraco doesn't ship by default. The aim of this primer is to give you the lay of the land on the backend, as sibling to the frontend primer. Each section sketches what's there and signposts a deeper doc for when you need it.

  • Backoffice extensions primer

    The frontend primer covers the public site and deliberately punts on the backoffice — the Umbraco admin UI at /umbraco. This repo ships four separate backoffice extension codebases, and this primer threads them together: how an extension reaches the backoffice at all (the App_Plugins manifest), how individual pieces of UI register themselves, how those pieces talk to the secured C# APIs behind them, and why each one is its own little Vite project rather than part of the public-site build.

  • Caching primer

    Caching in this codebase isn't one system — it's a dozen small decisions made in different places, each reaching for whatever cache fit that problem. That's fine, but it means "how is X cached?" has no single answer until you know which kind of thing X is. This primer maps the caches to the problems they solve, so you can tell which one to reach for (and what invalidates it) without spelunking.

  • Content modelling primer

    Everything editors see in the backoffice — pages, blocks, settings — starts life as an Umbraco content type, and every content type ends up as a generated C# class your controllers, services, and views work against. This primer is about that middle layer: the three shapes a content type can take, how compositions let them share fields without inheritance, how Models Builder turns backoffice configuration into typed code, and the couple of conventions (hand-written partials, ModelTypeAlias) that keep the generated layer safe to build on. It's the sibling of the backend primer, which picks up from here and covers what happens after you have a typed content model — the view-model-builder pipeline.

  • Frontend primer

    The public site's frontend lives in src/UmbracoCommunity.StaticAssets/ — a Vite + TypeScript + Lit project whose job is to build the JS, CSS, and other static assets that the Razor views in UmbracoCommunity.Web.UI load at request time. The aim of this primer is to give you the lay of the land — each section sketches what's there and signposts a tutorial, how-to, or source file for when you want to dig in.

  • Getting started primer

    Before any of the other primers are useful, you need a running site. This one is the on-ramp: what to install, the one command that gets you from a fresh clone to a working local site, and where the guardrails are before you start changing things. It doesn't replace Readme.md or BUILD.md — those are the command references, kept up to date as the build script changes — this primer is the orientation layer around them, with links out to the primer that covers each area in depth.

  • Third-party integrations primer

    The external dependencies this site talks to are, almost entirely, a handful of server-side data feeds that pull content from someone else's API — and the good news is they're all the same shape, so learn one and you can read or add any of them. (There are also a couple of avatar / build-time odds and ends, covered at the end.)

  • Multi-tenancy primer

    This site runs several distinct sites from one Umbraco instance — each site is a tenant, with its own root content node, its own domain, its own settings and content, but a shared media library, shared user accounts, and a single deployment. That arrangement is cheap and convenient, and it comes with exactly one rule you have to keep in your head for nearly everything you write. This primer gives you the five-minute orientation; the tutorial suite it links to has the depth.

  • SEO and structured data primer

    The content-modelling primer covers ICompositionSeo — the mixin that gives a page MetaTitle, MetaDescription, OgImage, Robots, and CustomSchema. This primer picks up from there: what happens to those fields between an editor filling them in and a <meta> tag or JSON-LD <script> landing in the rendered page. The whole pipeline funnels through one service and one view, which makes it a short primer — the point is mostly to save you from having to trace it yourself the first time.