Development

Everything you need to run this package locally, change it, and verify the change.

The repository contains the package itself plus a complete Umbraco site to run it in. That site is a development harness — it is never shipped, and IsPackable is false on it.

src/Cms/            the Umbraco host: content, templates, uSync export, dev certificate
src/ContentDashboard/  the package
scripts/            tooling that is not part of the build
docs/               these documents

Prerequisites

.NET 10 SDK
Node 22+ (the backoffice client is TypeScript built with Vite)

Nothing else. The site uses SQLite, created on first run.

First run

git clone https://github.com/SteveVaneeckhout/Our.Umbraco.ContentDashboard.git
cd Our.Umbraco.ContentDashboard
dotnet run --project src/Cms

The first build takes a while: it restores NuGet packages and runs npm ci + npm run build for the backoffice client, because wwwroot/ is generated and not committed.

On first boot the site, unattended:

creates src/Cms/umbraco/Data/Umbraco.sqlite.db,
installs Umbraco and the admin user,
runs the package migration,
and imports every document type, data type, template and document from src/Cms/uSync/v18 (uSync:Settings:ImportOnFirstBoot).

Then open https://localhost:44366/umbraco and sign in:


Email	`hello@example.com`
Password	`YVXVRvFlmUfwdGVWdprZWiZDKpwKiXfc`

Those credentials, and the certificate password below, are in src/Cms/appsettings.json on purpose. This is a throwaway local harness with no data worth protecting — treat every secret in this repository as public, because it is.

Open the Content section: the My Content, Scheduled and Ownership tabs are the package.

The demo content

The demo content is a theme-park site, “Coaster World”: 67 documents, all created by the unattended admin user, so the My Content tab has something in it immediately. Two deliberate future schedules keep the Scheduled tab non-empty — Acrobat publishes on 2026-12-01 and Alton Towers unpublishes on 2026-11-15. Clear them from each page’s publish flyout when they stop being useful.

Three optional steps

None of these are needed to run the site; each removes a specific annoyance.

1. Trust the development certificate

The site is served over HTTPS using a self-signed wildcard certificate for *.127.0.0.1.nip.io (committed at src/Cms/ssl/nip-io-wildcard.pfx — without it Kestrel will not start). Your browser will warn about it until you trust it:

# From an elevated PowerShell prompt
./src/Cms/ssl/Install-NipIoCertificate.ps1

The script adds only the public certificate to LocalMachine\Root, never the private key, and -Uninstall removes it again. Firefox needs security.enterprise_roots.enabled set to true to honour the machine store. New-NipIoCertificate.ps1 regenerates the certificate if you would rather not use the committed one.

Why nip.io rather than localhost: it resolves any *.127.0.0.1.nip.io name to loopback, which gives the harness real hostnames.

2. Set up the Umbraco MCP server

.mcp.json configures @umbraco-cms/mcp-dev, which lets an AI assistant read and change content through Umbraco’s management API. It needs credentials, and a fresh clone has none — uSync does not export users, so the API user does not exist in your new database.

In the backoffice, go to Users → API Users and create one with access to the Content section.
Open its profile and copy the client id and secret.
cp .env.example .env and fill them in. .env is gitignored.

scripts/verify-upgrade.mjs reads the same file for its live checks.

3. Work on the backoffice client

cd src/ContentDashboard/Client
npm install          # NOT --legacy-peer-deps
npm run watch        # rebuild on change
npm run build        # one-off
npm run generate-client   # regenerate src/api from the live OpenAPI document

Four things that will otherwise cost you an afternoon:

Never npm install --legacy-peer-deps. Umbraco’s own docs suggest it, but it skips the peer dependencies (lit, @umbraco-ui/uui, rxjs) that the TypeScript build needs for types. Without them you get a wall of “module has no exported member” errors.
Bump version in Client/public/umbraco-package.json whenever you ship a client change. Umbraco uses it as the cache-busting key (?umb__rnd=); leave it alone and browsers keep serving the old bundle.
Static web assets are baked at build time. After npm run build, the new chunks are only served once you rebuild and restart the site.
Stop the site before dotnet build. A running site holds the package DLL open and the copy step fails: Get-Process -Name Cms | Stop-Process -Force.

npm run generate-client reads https://localhost:44366/umbraco/openapi/contentdashboard.json, so the site has to be running. Run it whenever a controller signature or view model changes.

Building and testing

dotnet build Our.Umbraco.ContentDashboard.slnx
# (no test project yet)
dotnet format Our.Umbraco.ContentDashboard.slnx --verify-no-changes

Three things about this that are not obvious:

Tests are MSTest on Microsoft.Testing.Platform. The .NET 10 SDK refuses to run MTP projects through the old VSTest target, so global.json opts in with "test": { "runner": "Microsoft.Testing.Platform" }. In this mode a project is passed as dotnet test --project <path>, not positionally.
dotnet format --verify-no-changes is enforced by CI, so run it before opening a pull request. .gitattributes normalises the working tree to LF; without that the check fails on line endings alone.
-p:BuildClient=false skips the MSBuild target that shells out to npm. CI passes it everywhere and builds the client explicitly first, because that target only fires when the bundle is missing and will happily reuse a stale one.

Checking an Umbraco upgrade

node scripts/verify-upgrade.mjs              # static checks plus live probes
node scripts/verify-upgrade.mjs --static-only

It checks that the version pins agree across the host, the package and the client, then — with the site running — that the OpenAPI document generates, the App_Plugins bundle is served, and every parameterless endpoint answers. upgrading.md covers the half that needs judgement.

Contributing

Open an issue before a large change, so we can agree the shape of it first. For anything smaller: fork, branch, make sure dotnet build, dotnet format --verify-no-changes all pass, and open a pull request. CI runs exactly those.

New dependencies are worth a conversation: this package deliberately depends on nothing that is not published by Microsoft or Umbraco.