From debf92df19571a35cf862f3dc4f8cb3696d844dc Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Mon, 15 Jun 2026 15:53:48 -0400 Subject: [PATCH 1/5] Update npm package README: TypeScript-only examples and standalone dashboard Remove the C# AppHost example and keep TypeScript, aligning the sample with the official aspire-ts-starter template (Express API + Vite frontend). Add a second example showing how to wire backing services (Postgres, Redis) with references, and document starting the standalone dashboard with 'aspire dashboard run'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../pack-cli-npm-package.pointer.README.md | 65 ++++++++++++------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/eng/scripts/pack-cli-npm-package.pointer.README.md b/eng/scripts/pack-cli-npm-package.pointer.README.md index 6c86e43592f..0e6ef2e263e 100644 --- a/eng/scripts/pack-cli-npm-package.pointer.README.md +++ b/eng/scripts/pack-cli-npm-package.pointer.README.md @@ -13,48 +13,55 @@ Use an AppHost to describe how services, frontends, containers, databases, cache ## A simple app definition -The same application definition can be written in different languages. +You describe your app in a TypeScript AppHost (`apphost.mts`). The example below runs an Express API and a Vite frontend, exposes the API over HTTP, and wires the frontend to it: -__C#__ (`apphost.cs`) +```typescript +import { createBuilder } from './.aspire/modules/aspire.mjs'; -```csharp -var builder = DistributedApplication.CreateBuilder(args); +const builder = await createBuilder(); -var cache = builder.AddRedis("cache"); +// Run the Express API and expose its HTTP endpoint externally. +const app = await builder + .addNodeApp("app", "./api", "src/index.ts") + .withHttpEndpoint({ env: "PORT" }) + .withExternalHttpEndpoints(); -var api = builder.AddNodeApp("api", "./api", "src/index.ts") - .WithReference(cache) - .WaitFor(cache) - .WithHttpEndpoint(env: "PORT") - .WithExternalHttpEndpoints(); +// Run the Vite frontend after the API and inject the API URL for local proxying. +const frontend = await builder + .addViteApp("frontend", "./frontend") + .withReference(app) + .waitFor(app); -builder.AddViteApp("frontend", "./frontend") - .WithReference(api) - .WaitFor(api); +// Bundle the frontend build output into the API container for publish/deploy. +await app.publishWithContainerFiles(frontend, "./static"); -builder.Build().Run(); +await builder.build().run(); ``` -__TypeScript__ (`apphost.mts`) +Each builder call returns a promise, so `await` is used to get the resource before referencing it from another resource. `aspire run` builds and launches everything, then opens the dashboard. + +### Add backing services + +Resources like databases and caches are added the same way and connected with `withReference`. `waitFor` holds dependents until the resource is ready: ```typescript import { createBuilder } from './.aspire/modules/aspire.mjs'; const builder = await createBuilder(); +const postgres = await builder.addPostgres("postgres"); +const db = await postgres.addDatabase("db"); + const cache = await builder.addRedis("cache"); -const api = await builder +await builder .addNodeApp("api", "./api", "src/index.ts") - .withReference(cache) - .waitFor(cache) .withHttpEndpoint({ env: "PORT" }) - .withExternalHttpEndpoints(); - -await builder - .addViteApp("frontend", "./frontend") - .withReference(api) - .waitFor(api); + .withExternalHttpEndpoints() + .withReference(db) + .withReference(cache) + .waitFor(db) + .waitFor(cache); await builder.build().run(); ``` @@ -83,6 +90,16 @@ aspire run The native platform packages are installed through npm optional dependencies. Do not install this package with optional dependencies disabled, or the `aspire` launcher will not be able to find the native CLI binary. +## Standalone dashboard + +The Aspire dashboard shows logs, traces, metrics, and health checks for any app that exports OpenTelemetry, even without an AppHost. Start one in a single command: + +```bash +aspire dashboard run +``` + +This launches the dashboard with an OTLP endpoint your apps can point at via `OTEL_EXPORTER_OTLP_ENDPOINT`. Use `aspire dashboard run --help` to see options such as `--frontend-url`, `--otlp-grpc-url`, and `--allow-anonymous`. + ## Update ```bash From c4270f43bede3b7754e4dde6b0b1f7f5f4173eb4 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Mon, 15 Jun 2026 16:07:46 -0400 Subject: [PATCH 2/5] Address review: fix README test assertions and dashboard telemetry claim - Update NpmCliPackageTests to match the TypeScript-only README (the old __TypeScript__ heading was removed) and assert the C# example is gone and the standalone dashboard command is documented. - Standalone 'aspire dashboard run' surfaces OTLP logs/traces/metrics but not resource health checks (a resource-service/AppHost concept), so drop 'health checks' from the standalone-mode description. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/scripts/pack-cli-npm-package.pointer.README.md | 2 +- tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/eng/scripts/pack-cli-npm-package.pointer.README.md b/eng/scripts/pack-cli-npm-package.pointer.README.md index 0e6ef2e263e..aba690b3ddf 100644 --- a/eng/scripts/pack-cli-npm-package.pointer.README.md +++ b/eng/scripts/pack-cli-npm-package.pointer.README.md @@ -92,7 +92,7 @@ The native platform packages are installed through npm optional dependencies. Do ## Standalone dashboard -The Aspire dashboard shows logs, traces, metrics, and health checks for any app that exports OpenTelemetry, even without an AppHost. Start one in a single command: +The Aspire dashboard shows logs, traces, and metrics for any app that exports OpenTelemetry, even without an AppHost. Start one in a single command: ```bash aspire dashboard run diff --git a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs index 8cfff4e92b1..dd8be4bd056 100644 --- a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs @@ -186,11 +186,15 @@ public async Task PackScriptGeneratesPointerPackageMetadataMapAndReadme() Assert.Contains($"npm install -g {PackageName}", readme); Assert.Contains("The native platform packages are installed through npm optional dependencies.", readme); Assert.Contains("If you run `aspire update --self` from an npm install, the CLI points you back to this npm update command.", readme); - Assert.Contains("__TypeScript__ (`apphost.mts`)", readme); + Assert.Contains("TypeScript AppHost (`apphost.mts`)", readme); Assert.Contains("import { createBuilder } from './.aspire/modules/aspire.mjs';", readme); + Assert.Contains("aspire dashboard run", readme); Assert.DoesNotContain("apphost.ts", readme); Assert.DoesNotContain("./.aspire/modules/aspire.js", readme); Assert.DoesNotContain("__PACKAGE_NAME__", readme); + // The C# AppHost example was intentionally removed; the npm README is TypeScript-only. + Assert.DoesNotContain("apphost.cs", readme); + Assert.DoesNotContain("```csharp", readme); } [Theory] From 5090675beba97906f06af29e8df7fc951e09f650 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Mon, 15 Jun 2026 17:33:22 -0400 Subject: [PATCH 3/5] README: note that addPostgres/addRedis require 'aspire add' integrations The generated TypeScript SDK only exposes integration methods (addPostgres, addRedis) when the matching packages are installed, so document the 'aspire add postgresql' / 'aspire add redis' prerequisite for the backing services example. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/scripts/pack-cli-npm-package.pointer.README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/scripts/pack-cli-npm-package.pointer.README.md b/eng/scripts/pack-cli-npm-package.pointer.README.md index aba690b3ddf..69aa0af780f 100644 --- a/eng/scripts/pack-cli-npm-package.pointer.README.md +++ b/eng/scripts/pack-cli-npm-package.pointer.README.md @@ -66,7 +66,7 @@ await builder await builder.build().run(); ``` -## Install +`addPostgres` and `addRedis` become available once the matching integrations are installed with `aspire add postgresql` and `aspire add redis`. This package requires Node.js 20 or later. From 4f5a986a8f9b618b90251ba576b31388841cd1de Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Mon, 15 Jun 2026 17:45:00 -0400 Subject: [PATCH 4/5] Restore Install heading dropped from npm README Code review found the install instructions were orphaned under the 'Add backing services' subsection after the C# example removal. Restore the '## Install' heading so install steps render as their own section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/scripts/pack-cli-npm-package.pointer.README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/eng/scripts/pack-cli-npm-package.pointer.README.md b/eng/scripts/pack-cli-npm-package.pointer.README.md index 69aa0af780f..b0ab6d2d05f 100644 --- a/eng/scripts/pack-cli-npm-package.pointer.README.md +++ b/eng/scripts/pack-cli-npm-package.pointer.README.md @@ -68,6 +68,8 @@ await builder.build().run(); `addPostgres` and `addRedis` become available once the matching integrations are installed with `aspire add postgresql` and `aspire add redis`. +## Install + This package requires Node.js 20 or later. ```bash From 95a9533b03ddada9596c676f93dc3c67c0f1f263 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 19 Jun 2026 10:30:26 -0400 Subject: [PATCH 5/5] Address npm README review feedback Move the standalone dashboard section earlier in the npm README and link to the standalone dashboard documentation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../pack-cli-npm-package.pointer.README.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/eng/scripts/pack-cli-npm-package.pointer.README.md b/eng/scripts/pack-cli-npm-package.pointer.README.md index b0ab6d2d05f..44d515fdc69 100644 --- a/eng/scripts/pack-cli-npm-package.pointer.README.md +++ b/eng/scripts/pack-cli-npm-package.pointer.README.md @@ -11,6 +11,16 @@ Your stack, streamlined. Aspire is a multi-language, code-first orchestration an Use an AppHost to describe how services, frontends, containers, databases, caches, and connections fit together in code. The Aspire CLI runs the whole app locally, opens the OpenTelemetry dashboard for logs, traces, metrics, and health checks, and carries the same app model into deployment. +## Standalone dashboard + +The Aspire dashboard shows logs, traces, and metrics for any app that exports OpenTelemetry, even without an AppHost. Start one in a single command: + +```bash +aspire dashboard run +``` + +This launches the dashboard with an OTLP endpoint your apps can point at via `OTEL_EXPORTER_OTLP_ENDPOINT`. Use `aspire dashboard run --help` to see options such as `--frontend-url`, `--otlp-grpc-url`, and `--allow-anonymous`. See [Run the Aspire dashboard standalone](https://aspire.dev/dashboard/standalone/) for setup details. + ## A simple app definition You describe your app in a TypeScript AppHost (`apphost.mts`). The example below runs an Express API and a Vite frontend, exposes the API over HTTP, and wires the frontend to it: @@ -92,16 +102,6 @@ aspire run The native platform packages are installed through npm optional dependencies. Do not install this package with optional dependencies disabled, or the `aspire` launcher will not be able to find the native CLI binary. -## Standalone dashboard - -The Aspire dashboard shows logs, traces, and metrics for any app that exports OpenTelemetry, even without an AppHost. Start one in a single command: - -```bash -aspire dashboard run -``` - -This launches the dashboard with an OTLP endpoint your apps can point at via `OTEL_EXPORTER_OTLP_ENDPOINT`. Use `aspire dashboard run --help` to see options such as `--frontend-url`, `--otlp-grpc-url`, and `--allow-anonymous`. - ## Update ```bash