Skip to content
Purview Dev logo

AspireC4 supports both C# and TypeScript Aspire AppHosts. In a TypeScript AppHost, the Aspire integration exports the same diagram configuration, resource metadata, grouping, and relationship features through camel-cased asynchronous APIs. The C# registry source generator is not applied to TypeScript; TypeScript applications configure tags, kinds, groups, and metadata through the generated fluent API.

The Aspire CLI generates the TypeScript API surface under .aspire/modules/. Import createBuilder from the generated Aspire module, then add AspireC4 to the builder:

import { createBuilder } from "./.aspire/modules/aspire.mjs";
const builder = await createBuilder();
await builder
.addAspireC4({
configure: async (options) => {
options
.withTitle("My distributed application")
.withViewTitle("Architecture")
.withViewDescription("Generated from the Aspire resource graph");
},
})
.configureServer(async (resource) => {
resource.withLikeC4Details({
configure: async (options) => {
options.withLabel("Architecture diagram");
},
});
});
const api = await builder.addNodeApp("api", "../api", "index.ts");
await api.withLikeC4Details({
configure: async (options) => {
options
.withLabel("API")
.withTechnology("Node.js")
.withTag("backend");
},
});
const app = await builder.build();
await app.run();

Declare the integration and its Aspire dependencies in aspire.config.json:

{
"appHost": {
"path": "apphost.mts",
"language": "typescript/nodejs"
},
"sdk": {
"version": "13.6.5"
},
"packages": {
"Aspire.Hosting.JavaScript": "13.6.5",
"AspireC4.Hosting": "<version>"
}
}

Replace <version> with the current AspireC4.Hosting release on NuGet. The Aspire pins must be at least 13.6.5, the minimum in Requirements. A TypeScript AppHost does not compile C#, so the .NET 11 SDK requirement for the source generator does not apply to it. The repository sample points AspireC4.Hosting at ../../src/src/AspireC4/AspireC4.csproj so it exercises the local source instead of a published package.

global.json is the single source of truth for the Aspire AppHost SDK version. The sample repeats it in aspire.config.json, both as sdk.version and in the Aspire.Hosting.* package pins, because the Aspire CLI reads that file rather than global.json. just ts-validate compares the two and fails on drift; just ts-validate-fix rewrites the sample to match. The same check runs on every commit.

The sample at samples/typescript-app-host demonstrates:

  • AspireC4 configuration from apphost.mts.
  • Azure Redis and PostgreSQL resources running as local containers.
  • Redis Commander and PgWeb dashboard resources.
  • A TypeScript Node.js service with Redis and PostgreSQL references.
  • LikeC4 labels, descriptions, links, icons, metadata, tags, groups, and relationships.
  • Additional LikeC4 DSL and image folders from the repository assets directory.

Prerequisites are Docker, the Aspire CLI, and Bun. From the repository root:

Terminal window
cd samples/typescript-app-host
bun install
aspire restore
aspire start

aspire restore restores the integrations declared in aspire.config.json and regenerates .aspire/modules/. Once aspire start completes, open the Aspire dashboard URL printed by the CLI and select the LikeC4 resource or its architecture-diagram link. The sample also exposes the node-app /health, /ping/redis, and /ping/postgres endpoints through Aspire-assigned URLs.

For an interactive foreground session, the sample’s Bun script is equivalent to aspire run:

Terminal window
bun run dev

Stop a background session with:

Terminal window
aspire stop

Do not edit files under .aspire/modules/; Aspire owns and regenerates them. If the folder is missing or stale after a pull, clean, or branch switch, run:

Terminal window
aspire restore

When adding another Aspire integration, use aspire add <package> so Aspire updates aspire.config.json and regenerates the TypeScript API. Inspect .aspire/modules/aspire.mts to see the APIs currently available to apphost.mts.

The ER diagram is an optional second diagram and is additive, exactly as in a C# AppHost: addAspireC4() is the base, and the ER diagram is added on top of it. It is only compiled into the TypeScript API when the package is declared, so add it to packages in aspire.config.json and run aspire restore:

{
"packages": {
"Aspire.Hosting.JavaScript": "13.6.5",
"AspireC4.Hosting": "<version>",
"AspireC4.Hosting.EntityFrameworkCore": "<version>"
}
}

The fluent methods are exported in camel case (addAspireC4, withLikeC4Details, withEntityFrameworkDiagram, …). The ER output still lands in ./.aspirec4/erd/, and the per-service fidelity packages (AspireC4.EntityFrameworkCore and AspireC4.EntityFrameworkCore.ModelDump) are C# project references, so they apply to whatever service project declares the DbContext. See Entity Framework Core ER Diagrams.

The TypeScript AppHost writes to the same paths as the C# AppHost: ./.aspirec4/likec4/ for the architecture diagram and ./.aspirec4/erd/ for the ER diagram, both relative to the AppHost working directory. If you are upgrading from 13.5 and need the pre-13.6 layout unchanged, call withLegacyLayout() inside the configure callback:

await builder.addAspireC4({
configure: async (options) => {
options.withLegacyLayout();
},
});

That restores ./likec4/gen/ and ./erd/gen/ and keeps the dashboard rows flat as aspirec4 and aspirec4-er. An explicit output directory still wins, and the switch does not affect a hand-authored project folder. See Migration for the full list of breaking changes.