TypeScript AppHosts
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.
Generated modules
Section titled “Generated modules”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();aspire.config.json
Section titled “aspire.config.json”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.
Keeping the Aspire version in step
Section titled “Keeping the Aspire version in step”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.
Run the TypeScript sample
Section titled “Run the TypeScript sample”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
assetsdirectory.
Prerequisites are Docker, the Aspire CLI, and Bun. From the repository root:
cd samples/typescript-app-hostbun installaspire restoreaspire startaspire 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:
bun run devStop a background session with:
aspire stopGenerated modules notes
Section titled “Generated modules notes”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:
aspire restoreWhen 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.
Entity Framework Core diagrams
Section titled “Entity Framework Core diagrams”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.
Output paths and legacy mode
Section titled “Output paths and legacy mode”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.