From 36b6bc742f8d34309b9c7bc99410baf7afe1dbed Mon Sep 17 00:00:00 2001 From: Sebastien Ros Date: Tue, 26 May 2026 10:04:20 -0700 Subject: [PATCH 1/3] docs: document legacy apphost.ts compatibility for TypeScript AppHosts The 13.4 CLI transparently supports TypeScript AppHosts scaffolded by earlier CLI versions (apphost.ts importing from ./.modules/aspire.js): it routes generated SDK files to ./.modules/ and rewrites .mts/.mjs files to .ts/.js (extensions plus inter-module import specifiers) so existing imports resolve. aspire add/restore/run/start all keep working without user intervention. Document this behavior on the TypeScript AppHost page with a new 'Legacy apphost.ts projects (pre-13.4)' section and an opt-in 'Migrating to the new apphost.mts layout' subsection (rename file, update SDK import, update appHost.path, update tsconfig.apphost.json includes, delete ./.modules/ and re-restore). Also add a brief cross-reference in the 13.4 release notes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/app-host/typescript-apphost.mdx | 96 +++++++++++++++++++ .../content/docs/whats-new/aspire-13-4.mdx | 2 + 2 files changed, 98 insertions(+) diff --git a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx index c63d9719c..8ddde7e74 100644 --- a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx +++ b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx @@ -155,6 +155,102 @@ const api = await builder await builder.build().run(); ``` +## Legacy `apphost.ts` projects (pre-13.4) + +TypeScript AppHosts scaffolded by Aspire CLI versions earlier than 13.4 use a slightly different layout: the entry point is `apphost.ts` (not `apphost.mts`), and the generated TypeScript SDK lives in `./.modules/` (not `./.aspire/modules/`): + + + +- my-apphost/ + - .modules/ Generated TypeScript SDK (do not edit) + - aspire.ts + - base.ts + - transport.ts + - apphost.ts Your AppHost entry point + - aspire.config.json Aspire configuration + - package.json + - tsconfig.apphost.json + + + +The pre-13.4 entry point imports the SDK with the `.js` extension: + +```typescript title="apphost.ts (pre-13.4)" +import { createBuilder } from './.modules/aspire.js'; +``` + +### Compatibility in 13.4 + +The 13.4 Aspire CLI keeps these projects working without any changes: + +- When the CLI sees an `apphost.ts` file with no `apphost.mts` alongside it — either because `aspire.config.json` sets `appHost.path` to `apphost.ts`, or because a disk scan finds `apphost.ts` and no `apphost.mts` — it switches to the legacy output layout for that project. +- Generated SDK files are written to `./.modules/` instead of `./.aspire/modules/`. +- Generated files are rewritten from `.mts`/`.mjs` to `.ts`/`.js`, including the inter-module import specifiers inside the SDK, so the existing `./.modules/aspire.js` import in your `apphost.ts` continues to resolve. + +`aspire add`, `aspire restore`, `aspire run`, and `aspire start` all continue to work against an existing `apphost.ts` project with no edits required. + + + +### Migrating to the new `apphost.mts` layout + +If you'd like to move an existing project to the new default layout, the migration is mechanical. The steps below assume an AppHost root with `apphost.ts`, `./.modules/`, and the legacy `appHost.path` value: + + + +1. **Rename the entry point file.** + + ```bash + git mv apphost.ts apphost.mts + ``` + +2. **Update the SDK import** in `apphost.mts` to use the new folder and the `.mjs` extension: + + ```typescript title="apphost.mts" del={1} ins={2} + import { createBuilder } from './.modules/aspire.js'; + import { createBuilder } from './.aspire/modules/aspire.mjs'; + ``` + +3. **Update `appHost.path`** in `aspire.config.json`: + + ```json title="aspire.config.json" del={3} ins={4} + { + "appHost": { + "path": "apphost.ts", + "path": "apphost.mts", + "language": "typescript/nodejs" + } + } + ``` + +4. **Update `tsconfig.apphost.json`** so its `include` (and any related glob) entries point at the new file and folder. Replace references to `apphost.ts` with `apphost.mts`, and references to `.modules/` with `.aspire/modules/`. For example: + + ```json title="tsconfig.apphost.json" del={4,5} ins={6,7} + { + "compilerOptions": { /* ... */ }, + "include": [ + "apphost.ts", + ".modules/**/*.ts" + "apphost.mts", + ".aspire/modules/**/*.mts" + ] + } + ``` + +5. **Delete the old generated SDK folder and regenerate.** The CLI now writes the SDK under `./.aspire/modules/`, so the old folder is no longer used: + + ```bash + rm -rf .modules + aspire restore + ``` + + If your `.gitignore` ignores `.modules/`, replace that entry with `.aspire/` (or `.aspire/modules/`) to match the new location. + + + +After migrating, `aspire run` behaves exactly the same as before — the CLI now uses the modern output path because `apphost.mts` is present. + ## Package managers The Aspire CLI supports the following package managers at the **AppHost root** — the directory that contains your `apphost.mts` and `aspire.config.json`. The CLI selects between them by inspecting package manager signals, including the `packageManager` field in `package.json`, lock files, and package manager configuration in the AppHost root. diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx index c73b8c97e..480e828cc 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx @@ -123,6 +123,8 @@ Aspire 13.4 strengthens the TypeScript experience by validating TypeScript AppHo The documentation now treats TypeScript AppHosts as a first-class peer to C# AppHosts: AppHost-focused guides and integration pages include TypeScript examples alongside C# where the API is available. The release also adds a new set of TypeScript samples so you can start from working `apphost.mts` projects instead of translating from C#. +Existing TypeScript AppHosts scaffolded by earlier CLI versions (using `apphost.ts` and `./.modules/aspire.js`) continue to work on 13.4 without changes — the CLI transparently routes generated SDK files to the legacy `./.modules/` folder and rewrites them to `.ts`/`.js` so existing imports resolve. See [Legacy `apphost.ts` projects (pre-13.4)](/app-host/typescript-apphost/#legacy-apphostts-projects-pre-134) for details and an opt-in migration to the new `apphost.mts` layout. + For setup details, see [TypeScript AppHosts](/app-host/typescript-apphost/). To explore working examples, browse the [Aspire samples](/reference/samples/). From 7092da04da544d11514a2b7c72c5813024d850e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Ros?= Date: Tue, 26 May 2026 10:22:39 -0700 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/frontend/src/content/docs/app-host/typescript-apphost.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx index 8ddde7e74..b81406169 100644 --- a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx +++ b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx @@ -231,7 +231,7 @@ If you'd like to move an existing project to the new default layout, the migrati "compilerOptions": { /* ... */ }, "include": [ "apphost.ts", - ".modules/**/*.ts" + ".modules/**/*.ts", "apphost.mts", ".aspire/modules/**/*.mts" ] From 19d8a59ce4c37235de59238322395c3711a0eb36 Mon Sep 17 00:00:00 2001 From: David Pine Date: Tue, 26 May 2026 14:33:43 -0500 Subject: [PATCH 3/3] Update src/frontend/src/content/docs/app-host/typescript-apphost.mdx --- src/frontend/src/content/docs/app-host/typescript-apphost.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx index b81406169..c61cb851e 100644 --- a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx +++ b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx @@ -157,7 +157,7 @@ await builder.build().run(); ## Legacy `apphost.ts` projects (pre-13.4) -TypeScript AppHosts scaffolded by Aspire CLI versions earlier than 13.4 use a slightly different layout: the entry point is `apphost.ts` (not `apphost.mts`), and the generated TypeScript SDK lives in `./.modules/` (not `./.aspire/modules/`): +TypeScript AppHosts scaffolded by Aspire CLI versions earlier than 13.4 use a slightly different layout: the entry point was `apphost.ts` (not `apphost.mts`), and the generated TypeScript SDK lives in `./.modules/` (not `./.aspire/modules/`):