This repository is the Template: a GitHub template repository. Selecting Use this template creates a new repository seeded with its contents, and the Blazor Web App that repository becomes is a Generated App. This README describes the Template; a Generated App is expected to replace it.
The Template is intended to give every Generated App:
- A server-rendered Blazor Web App on .NET 10.
- Tailwind CSS styling with a light/dark Theme and a selectable Palette that tints the accent color and the surfaces, both persisted in cookies.
- Auth0 authentication and authorization, distinguishing a Visitor (unauthenticated), a User (authenticated) and an Admin (a User with the Admin role).
See CONTEXT.md for the exact meaning of these terms.
Status: early stage. The Template currently contains the Shared Kernel (src/Domain), the Blazor Web App
scaffold (src/UI: a Home page, a nav menu, a NotFound page and the Tailwind CSS v4 build), sign-in and sign-out through
Auth0 with the Admin role mapped, a Profile page listing a User's own claims, an Admin page only an Admin can
open, the light/dark Theme, the Palette that tints the accent and the surfaces, and their tests.
The Theme is chosen from a Light, Dark and System group in the nav, on desktop and in the mobile menu. Each button
posts to /theme, which stores the choice in a theme cookie and returns to the same page, so it works without
JavaScript. The server reads the cookie as it renders and writes data-theme on <html>, so the first paint already
uses the chosen Theme. System, the default, deletes the cookie and follows the OS preference.
The Palette is chosen from a menu of 17 Tailwind hues, from Red to Rose, opened from a swatch button in the nav on desktop and shown
as a Palette section in the mobile menu. Each tile posts to /palette, which stores the hue in a palette cookie and returns to the
same page, again without JavaScript. The server writes data-palette on <html>, and a CSS rule for each hue swaps the accent scale.
The Palette tints the accent (buttons, links and highlights) and the surfaces (the page, cards, nav, footer, borders, dividers and hover
fills), in both Themes. Text stays neutral, and the Palette menu's own panel stays slate so each swatch shows its true hue.
Blue, the default, renders no attribute.
| Version | Date | Title | Blog post |
|---|---|---|---|
| v0.0.185 | 2026-10-26 | docs(claude): Match the review:claude exception to PROCESS.md | Post |
| v0.0.184 | 2026-10-26 | fix(sandcastle): Pin the structured-output roles and scope the review:claude rule | Post |
| v0.0.183 | 2026-10-26 | chore: Re-apply the repo-ci-baseline Template | Post |
| v0.0.182 | 2026-10-26 | chore: Migrate Sandcastle to the repo-ci-baseline Template | Post |
| v0.0.181 | 2026-10-26 | ci(sandcastle): Start a follow-up pass when Claude Review completes | Post |
| v0.0.180 | 2026-10-20 | chore: Re-apply the repo-ci-baseline Template | Post |
| v0.0.179 | 2026-10-20 | chore: Re-apply the repo-ci-baseline Template | Post |
| v0.0.178 | 2026-10-19 | fix(sandcastle): Let the critique see overlap-held issues, and don't fail the run on a comments read | Post |
| v0.0.177 | 2026-10-19 | fix(sandcastle): Fix the same-file overlap check's review findings | Post |
| v0.0.176 | 2026-10-19 | feat(sandcastle): Don't build two issues at once that change the same file | Post |
-
Select Use this template on the repository page to create your own repository, then clone it:
git clone https://github.com/<your-account>/<your-repo>.git cd <your-repo>
-
Install the prerequisites:
- The .NET SDK
10.0.401, as pinned in global.json (later 10.0 feature bands are accepted). - Node.js and pnpm (
corepack enable), used by the Tailwind CSS build, the git hooks and the lint tools. The repo refusesnpm install. - yamllint, which the pre-push hook runs on changed YAML files.
- The .NET SDK
-
Install the pnpm packages, then build and test each test project:
pnpm install dotnet build Blazor-Server.slnx (for project in tests/*/*.csproj; do dotnet test --project "$project" || exit 1; done)
Run the test projects one at a time, as
scripts/gate.shand CI do. Under Microsoft Testing Platform,dotnet test --solutioncan report zero tests even when the projects pass.pnpm installmust come first:dotnet buildruns the Tailwind CLI to writesrc/UI/wwwroot/css/app.css, and fails with an error namingpnpm installwhen the packages are missing. Run the app with:dotnet run --project src/UI
Or run it through the Aspire AppHost, which starts the UI as
WebAppand opens the Aspire dashboard with its logs, traces and metrics.aspire runneeds the Aspire CLI;dotnet runworks without it. The AppHost'shttpsprofile, whichaspire runuses, serves both the dashboard andWebAppover HTTPS (https://localhost:7161), and thehttpprofile needs no developer certificate:aspire run dotnet run --project src/AppHost --launch-profile https dotnet run --project src/AppHost --launch-profile http
The
httpsprofile needs a trusted developer certificate. Trust it once withdotnet dev-certs https --trust. On Linux, .NET also reads the trusted copy only when$HOME/.aspnet/dev-certs/trustis inSSL_CERT_DIR, for exampleexport SSL_CERT_DIR="$HOME/.aspnet/dev-certs/trust:/etc/ssl/certs"(see https://aka.ms/dev-certs-trust).In Development, the UI reports its health at
/healthand/alive.While editing markup,
pnpm --dir src/UI run watch:cssrebuilds the CSS as you save. -
Optionally enable the git hooks in
.github/hooks(markdownlint on commit, andscripts/gate.shon push):git config core.hooksPath .github/hooks
scripts/gate.shlints the files changed since the branch leftorigin/main, then builds and tests the solution in Release. Run it by hand to check a branch before pushing.
The app won't start without an Auth0 tenant's settings: it validates Auth0:Domain, Auth0:ClientId and
Auth0:ClientSecret on startup and names any that's missing.
-
In the Auth0 dashboard, create an application of type Regular Web Application. Sign-in uses the authorization-code flow, so leave the Authorization Code grant on (it is by default). The app sends the client secret only to Auth0's token endpoint, from the server.
-
In the application's settings, add:
- Allowed Callback URLs:
http://localhost:5112/callback, https://localhost:7161/callback - Allowed Logout URLs:
http://localhost:5112/, https://localhost:7161/
Sign-in works on the
httpprofile only onlocalhost, because the browser keeps Auth0'sSecuresign-in cookies forhttp://localhostalone. Thehttpsprofile is the safer choice anywhere else. - Allowed Callback URLs:
-
Under User Management → Roles, create a role named
Adminand assign it to the users who should be an Admin. -
Under Actions → Library, create a Post Login Action that adds the user's roles to the ID token, and add it to the Login flow:
exports.onExecutePostLogin = async (event, api) => { api.idToken.setCustomClaim('https://blazor-server-template/roles', event.authorization?.roles ?? []); };
-
Store the application's settings as user secrets.
Auth0:Domainis the tenant's host only, with nohttps://(for examplemy-tenant.us.auth0.com):dotnet user-secrets set "Auth0:Domain" "<your-tenant>.auth0.com" --project src/UI dotnet user-secrets set "Auth0:ClientId" "<client-id>" --project src/UI dotnet user-secrets set "Auth0:ClientSecret" "<client-secret>" --project src/UI
The AppHost shares the UI's user secrets, so
aspire runreads the same values and passes them toWebAppasAuth0__Domain,Auth0__ClientIdandAuth0__ClientSecret. When one is missing, the Aspire dashboard asks for it. Outside Development, set those environment variables instead.
Auth0:RoleClaimType names the claim the roles arrive in. It defaults to https://blazor-server-template/roles, the
claim the Action above sets; change both together. The app maps each role in that claim to a .NET role, so an Admin
there satisfies the Admin policy.
- Replace this README with one that describes your Generated App.
- Give your app its own user secrets: replace the
UserSecretsIdin bothsrc/UI/UI.csprojandsrc/AppHost/AppHost.csprojwith one new GUID (for example fromuuidgen). Otherwise every app made from this template reads and writes the sameAuth0:*secrets on your machine. - Repoint the badges at your own repository, or remove them.
- Decide whether to keep the release automation: release.yml tags a release and
opens a release-notes PR for every merged PR, which also copies
README.mdtodocs/README.md. Delete it if you don't want it. - The release-notes PR adds a blog post written by release_post.py.
Add an
ANTHROPIC_API_KEYrepository secret to open each post with a short AI summary; without it, posts skip the summary. Run backfill-blog-posts.yml by hand to write posts for past releases that lack one, or setregenerateto rewrite them all. It opens one PR and never creates tags or Releases. - docs/index.html is the GitHub Pages home page. Repoint its header links at your
repository, or delete it and
docs/.nojekyllif you don't publish Pages.
src/AppHost/ -- Aspire AppHost: runs the UI as the WebApp resource
src/Domain/ -- Shared Kernel: Result, Result<T>, ApplicationConstants
src/ServiceDefaults/ -- Aspire service defaults: OpenTelemetry and health checks
src/UI/ -- Blazor Web App (server-rendered)
src/UI/Components/Features/ -- One folder per feature slice (e.g. Home)
src/UI/Styles/ -- Tailwind CSS v4 source
tests/AppHost.Tests.Integration/ -- AppHost integration tests (Aspire.Hosting.Testing)
tests/Architecture.Tests/ -- Architecture rules (Domain's dependencies, UI's references, slice boundaries)
tests/Domain.Tests.Unit/ -- Shared Kernel unit tests
tests/UI.Tests.Unit/ -- UI component tests (bUnit)
tests/UI.Tests.Integration/ -- UI integration tests (WebApplicationFactory)
tests/UI.Tests.E2E/ -- End-to-end tests (Playwright, through the AppHost)
docs/adr/ -- Architecture decision records
aspire.config.json -- Aspire CLI settings, pointing at src/AppHost
CONTEXT.md -- Domain language
.sandcastle/ -- Sandcastle agent setup
docs/CODING_STANDARDS.md -- Coding standards
CLAUDE.md, .claude/ -- Claude Code instructions, rules and skills
.github/workflows/ -- CI, code analysis, linting and release workflows
.github/scripts/ -- Release blog post generator, backfill and pytest tests
.github/copilot-instructions.md -- Copilot PR review checklist, generated from the code-review skill
- Name branches
feature/{issue}-{slug}for issue work,fix/{issue}-{slug}for bug fixes,hotfix/{issue}-{slug}for urgent fixes, orchore/{slug}for maintenance with no issue, for examplefeature/14-add-root-readme. - Issues labelled
Sandcastleare worked by Sandcastle agents, which open a pull request for review. - Read CONTRIBUTING.md, the Code of Conduct and the Security Policy before contributing.
Licensed under the MIT License.