Cratis.Templates 1.2.2

Cratis Templates

This repository contains all creation templates used by Cratis. It holds dotnet new project templates you can use to scaffold new event-sourced and CQRS applications built with Cratis Chronicle (event-sourcing database and processing runtime) and Cratis Arc (CQRS application framework for ASP.NET Core). Everything is MIT licensed and free to use.

Available templates

Builds

How to use

Quick steps to scaffold projects from these templates:

• Install the published templates from NuGet.org (one-time):

dotnet new install Cratis.Templates

• Optional: install a specific version:

dotnet new install Cratis.Templates::<version>

• Optional: install prerelease builds from GitHub Packages:

dotnet nuget add source --name cratis-github --username <github-username> --password <github-token> --store-password-in-clear-text https://nuget.pkg.github.com/cratis/index.json
dotnet new install Cratis.Templates::<version> --nuget-source https://nuget.pkg.github.com/cratis/index.json

• List available templates and note the Short Name you want:

dotnet new --list

• Create a new project from a template (replace <shortname>):

dotnet new <shortname> -n MyApp -o MyApp

• Many templates accept parameters; run dotnet new <shortname> --help to see available options.

dotnet new cratis -n MyApp -o MyApp --allow-scripts yes

• Uninstall when needed:

dotnet new uninstall Cratis.Templates

Updating installed templates

To update to the latest version:

dotnet new update

This updates all installed template packages to their latest versions.

To update only Cratis.Templates:

dotnet new uninstall Cratis.Templates
dotnet new install Cratis.Templates

To check which version you currently have installed:

dotnet new list

Look for Cratis.Templates in the output to see the installed version.

To update to a specific version:

dotnet new uninstall Cratis.Templates
dotnet new install Cratis.Templates::<version>

Build & Test Locally

Prerequisites:

• .NET SDK (recommended 8.0+)
• Latest stable Node.js and npm (if testing frontend/Vite templates; CI resolves the latest Node release)

Pack and install the templates locally

dotnet pack Cratis.Templates.csproj -c Release -o ./nupkgs
dotnet new -i ./nupkgs

If you prefer to install directly from the template folder (unpacked):

dotnet new -i ./Cratis.Templates

List available templates and find the short name

dotnet new --list

Create a test project from a template (replace <shortname> with the template short name)

dotnet new <shortname> -n MyTestApp
cd MyTestApp
dotnet restore
dotnet build
dotnet run

If the generated project includes a frontend (Vite/Node)

cd path/to/generated/frontend
npm install
npm run dev

TypeScript compiler and lint tooling

The starters use the latest TypeScript 7 compiler. Following TypeScript's side-by-side setup, @typescript/native aliases TypeScript 7 and supplies the tsc executable used by the build. The typescript alias points to the latest @typescript/typescript6 compatibility package for tools such as typescript-eslint that need the JavaScript compiler API, which TypeScript 7.0 does not provide. This does not switch the build to the older tsc6 executable.

Check the compiler actually used by the build with ./node_modules/.bin/tsc --version rather than inferring it from the compatibility package's name.

Verify the emitted frontend asset layout

./verify-asset-layout.sh

Scaffolds both Vite-based templates, builds their frontends, and checks that every hashed build artifact lands under wwwroot/assets/ rather than at the wwwroot root. A flat root layout cannot be expressed as a reverse-proxy, CDN or WAF path rule — the artifacts are hash-named, change every build and share no prefix — so the failure only shows up at deployment, as a blank page. CI runs the same script against the applications it has already generated.

Pass application directories to check ones you have already scaffolded:

./verify-asset-layout.sh path/to/MyTestApp

Verify the registration identity

The cratis and cratis-aspire samples return SomeId, an EventSourceId<Guid>-derived identity, alongside the registered event. This tells Arc to append under that identity and return the same value to the caller. A raw Guid in the tuple is only a response value, not an append identity. The generated TypeScript response remains Guid.

With .NET 10 and Python 3 installed, check already-scaffolded application directories:

./verify-registration-identity.sh path/to/MyApp path/to/MyAspireApp/MyAspireApp

This regenerates proxies and checks their response type, executes the actual scaffolded registration command, compares its response to the appended event and projected Listing.Id, and runs a follow-up command using that response identity. It uses in-process Arc/Chronicle scenarios, not a running Chronicle server; the lookup scenario is seeded with the verified projected instance under its own identity. Test-only packages and runner files stay under the repository's ignored .ai-work/; they are not added to generated applications. CI runs this check for both templates.

Uninstall the local template when finished

dotnet new -u <package-id-or-folder>

Iterate on the template sources, repack, and reinstall to test changes quickly.

The Cratis ecosystem

This project is part of Cratis — free, MIT-licensed tools for building event-sourced and CQRS applications.

• Chronicle — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. Docs
• Chronicle clients — first-class .NET SDK, plus TypeScript, Kotlin/Java, and Elixir; Python coming soon (pre-alpha). AI agents connect through the Chronicle MCP server.
• Arc — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. Docs
• Components — React components aligned with Arc patterns. Docs
• CLI + Workbench — inspect and diagnose Chronicle from the terminal or the browser. Docs
• Model-first layer (experimental) — Studio, Screenplay, Stage, Scene, Prologue
• Supporting — Fundamentals, Specifications, Synopsis, Lens, Narrator, and free AI tooling (preview); Ensemble coming soon (pre-release)
• Samples — runnable event sourcing and CQRS samples for the whole stack

Everything Cratis publishes today is MIT licensed and free to use.