Support alternative TypeScript AppHost toolchains

[sebastienros]

Description

TypeScript AppHosts currently assume npm/npx, which breaks local workflows when the project is set up for Bun, Yarn, or pnpm. This updates the CLI to detect the effective Node-compatible toolchain from project metadata and use the matching install, run, watch, warning, and doctor behavior.

The change keeps the existing TypeScript AppHost scaffolding story and does not add separate runtime-specific templates. It also stays scoped to Node-compatible toolchains for now; Deno is not included in this pass.

• Detect the AppHost toolchain from package.json packageManager metadata and common lockfiles.
• Rewrite TypeScript AppHost install and launch commands during scaffolding and guest project execution to use the detected toolchain.
• Add an aspire doctor environment check plus tool-specific warnings and install guidance for missing Bun, Yarn, or pnpm tooling.
• Preserve the existing extension-backed node launch capability so non-npm toolchains still debug correctly in VS Code.

No additional dependencies are introduced beyond the selected JavaScript toolchain. Documentation tracking lives in microsoft/aspire.dev#713.

Fixes #15812

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire.dev issue:
      • Document TypeScript AppHost toolchain support aspire.dev#713
  • No

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for detecting and using non-npm JavaScript toolchains (Bun/Yarn/pnpm) for TypeScript AppHosts across scaffolding, runtime execution, and aspire doctor environment checks.

Changes:

• Detect TypeScript AppHost toolchain via package.json packageManager and lockfile heuristics, and rewrite runtime commands accordingly.
• Add aspire doctor environment check for required JS tooling and improve tool-specific missing-command messaging and install links.
• Update/extend tests to cover new toolchain resolution and missing-tool warning behavior.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/Aspire.Cli.Tests/Utils/CommandPathResolverTests.cs	Expands tests for tool-specific missing-command messages and install links.
tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs	Registers the new TypeScript AppHost tooling environment check in test DI.
tests/Aspire.Cli.Tests/Utils/AutomaticNpmInstallWarningTests.cs	Broadens warning detection tests to include Bun/Yarn/pnpm missing-tool messages.
tests/Aspire.Cli.Tests/Projects/TypeScriptAppHostToolchainResolverTests.cs	Adds tests for toolchain resolution and runtime spec rewriting.
tests/Aspire.Cli.Tests/Commands/TypeScriptAppHostToolingCheckTests.cs	Adds tests validating doctor check behavior for available/missing toolchains.
src/Aspire.Cli/Utils/EnvironmentChecker/TypeScriptAppHostToolingCheck.cs	Introduces a new environment check for TypeScript AppHost JS tooling.
src/Aspire.Cli/Utils/CommandPathResolver.cs	Adds tool-specific missing messages and a new installation-link helper.
src/Aspire.Cli/Utils/AutomaticNpmInstallWarning.cs	Extends warning matching to multiple JS toolchains (not just npm/npx).
src/Aspire.Cli/Scaffolding/ScaffoldingService.cs	Applies toolchain-specific runtime commands during dependency installation.
src/Aspire.Cli/Projects/TypeScriptAppHostToolchainResolver.cs	New resolver that detects toolchain and rewrites runtime command specs.
src/Aspire.Cli/Projects/GuestAppHostProject.cs	Applies toolchain-specific runtime spec selection for guest execution.
src/Aspire.Cli/Program.cs	Registers the new TypeScript AppHost tooling environment check in production DI.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 16162

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 16162"

[davidfowl]

This needs an end to end test

[davidfowl]

PR Testing Report — Manual Dogfood Validation

CLI Version: 13.3.0-pr.16162.g3ed57ffd ✅ matches head commit 3ed57ffd

Scenarios Tested

#	Scenario	Result	Details
1	TS empty project created with npm (default)	✅ Passed	aspire new aspire-ts-empty scaffolds correctly, package-lock.json present
2	aspire doctor detects npm toolchain	✅ Passed	Reports TypeScript AppHost tooling found (npm, npx)
3	pnpm detection via packageManager field	✅ Passed	Set "packageManager": "pnpm@10.12.1" → doctor reports pnpm
4	bun detection via bun.lockb lockfile	✅ Passed	Created bun.lockb → doctor reports bun
5	No false positive on C# project	✅ Passed	aspire-empty (C#) shows .NET SDK check only, no TS tooling check
6	Warning when npm/npx missing from PATH	✅ Passed	Clear ❌ TypeScript AppHost requires npm/npx errors with install guidance
7	Default scaffolding uses npm	✅ Passed	aspire new aspire-ts-empty produces package-lock.json and node_modules

Notes

• Tested on macOS ARM64 via local dogfood install
• aspire-starter template has a pre-existing Blazor build error (CS0234 Components namespace) unrelated to this PR
• Toolchain detection works correctly for all three paths: packageManager field, lockfile presence, and npm default fallback
• No false positives observed on non-TS projects

[sebastienros]

Because Deno is not just “another package manager” here; it is a different runtime model. This pass worked by keeping the existing TypeScript AppHost shape and only swapping the Node-compatible toolchain underneath it.

The bigger changes for Deno are:

• Project shape differs. This PR assumes package.json, lockfiles, npm-style scripts, and often node_modules. Deno commonly centers on deno.json, tasks/import maps, and may not use that same layout.
• Execution differs. The current runtime flow is basically “install deps, then run/watch with tsx and nodemon.” Deno would more likely want deno run, deno task, or deno --watch, so it is not a simple command alias.
• Permissions become part of the model. Deno often needs explicit --allow-* flags, which means the CLI/runtime contract would need a way to represent those.
• Detection and doctor checks differ. The current detection logic looks for packageManager and Node-oriented lockfiles, and aspire doctor checks for npm/bun/yarn/pnpm commands. Deno would need its own detection rules and dependency checks.
• Debugging and tooling differ. We preserved the existing VS Code node launch path for non-npm toolchains; Deno likely needs its own debug/launch behavior.
• No prior art in the current hosting layer. Bun/Yarn/pnpm already matched existing JavaScript hosting concepts. We did not find equivalent built-in Deno support to extend.

So Bun/Yarn/pnpm fit as “same AppHost model, different Node-compatible toolchain”. Deno looks more like “new AppHost runtime mode”, which is why it was deferred.

Bun fit because we could support it with bounded changes while keeping the same overall model:

• same package.json / lockfile / script-based project shape
• same generated AppHost and dependency flow
• same runtime abstraction: install, execute, watch
• existing prior art in hosting (WithBun already existed)

Deno is more involved because it pushes on parts of the model we do not represent today:

• deno.json / tasks / import maps instead of the current package.json flow
• deno run / deno task / --watch instead of the current tsx / nodemon assumptions
• explicit --allow-* permissions
• different detection and aspire doctor rules
• likely different debug / VS Code launch behavior
• possibly different scaffolded/generated file shape

[rickylabs]

Thanks for the detailed breakdown @sebastienros — I appreciate the time you put into this and the quality of this PR overall. That said, after reviewing the actual code changes, I'd like to respectfully push back on some of the points:

Because Deno is not just "another package manager" here; it is a different runtime model. This pass worked by keeping the existing TypeScript AppHost shape and only swapping the Node-compatible toolchain underneath it.

Looking at TypeScriptAppHostToolchainResolver.CreateExecuteCommand() in this PR, the Bun execute command is bun run {appHostFile} — Bun directly executes the TypeScript AppHost as a runtime. By contrast, Yarn and pnpm delegate to tsx (Node.js) via yarn exec tsx ... / pnpm exec tsx .... So Bun is the only alternative in this PR where the underlying runtime actually changes, not just the package manager. A Deno equivalent would follow the exact same pattern: deno run {appHostFile}. The "different runtime model" characterization applies equally to Bun here.

Project shape differs. This PR assumes package.json, lockfiles, npm-style scripts, and often node_modules. Deno commonly centers on deno.json, tasks/import maps, and may not use that same layout.

As of Deno 2.7 (February 2026), Deno has robust package.json support including version overrides, nested dependency trees, and node_modules. The deno.json / import maps layout is an alternative, not a requirement. Deno can work with the exact same package.json-based project structure that TryGetToolchainFromPackageJson() already handles in this PR. This is no different from how Bun has bunfig.toml as an alternative to package.json.

Execution differs. The current runtime flow is basically "install deps, then run/watch with tsx and nodemon." Deno would more likely want deno run, deno task, or deno --watch, so it is not a simple command alias.

But that's exactly what Bun does in this PR. CreateExecuteCommand returns bun run {appHostFile} (not tsx), and CreateWatchCommand returns bun --watch run {appHostFile} (not nodemon). Deno equivalents would be deno run --allow-all {appHostFile} and deno run --watch --allow-all {appHostFile} — the same shape, same complexity, same number of lines in the switch expression.

Permissions become part of the model. Deno often needs explicit --allow-* flags, which means the CLI/runtime contract would need a way to represent those.

Deno 2+ defaults to permissive mode when running scripts from package.json. For the aspire run / local dev scenario, --allow-all is a perfectly reasonable default — exactly like how Node.js and Bun run without restrictions. This would be a single flag in CreateExecuteCommand, not a model change.

Detection and doctor checks differ. The current detection logic looks for packageManager and Node-oriented lockfiles, and aspire doctor checks for npm/bun/yarn/pnpm commands. Deno would need its own detection rules and dependency checks.

Agreed, but this is mechanical, bounded work — the same work that was already done for Bun/Yarn/pnpm in this PR. Concretely it would mean:

• Add Deno to the TypeScriptAppHostToolchain enum
• Add deno.lock / deno.json detection in Resolve() (same pattern as bun.lock / pnpm-lock.yaml)
• Add "deno" to TryParseToolchain() for the packageManager field
• Add a "deno" entry in CommandPathResolver.s_commandMetadata
• Add a "deno is not installed..." prefix in MissingJavaScriptToolWarning.s_missingToolPrefixes

These are entries in existing switch expressions and arrays, not new abstractions.

Debugging and tooling differ. We preserved the existing VS Code node launch path for non-npm toolchains; Deno likely needs its own debug/launch behavior.

Looking at ApplyToRuntimeSpec() line 128: ExtensionLaunchCapability = baseRuntimeSpec.ExtensionLaunchCapability — this PR preserves the "node" VS Code launch capability even for Bun. Bun doesn't get its own debug adapter here; it reuses the Node.js debugger. A Deno initial pass could do exactly the same — keep "node" as the launch capability (Deno supports the V8 inspector protocol) and defer Deno-specific debugging to a follow-up. The debugging concern was effectively solved for Bun by not solving it, and that's a perfectly valid approach for Deno too.

No prior art in the current hosting layer. Bun/Yarn/pnpm already matched existing JavaScript hosting concepts. We did not find equivalent built-in Deno support to extend.

This is true for the hosting layer (WithBun(), WithYarn(), etc.), but this PR's scope is the CLI toolchain resolver (TypeScriptAppHostToolchainResolver), which is entirely new code — there was no prior art for Bun/Yarn/pnpm here either. The community toolkit already provides Deno hosting resources separately, and that's orthogonal to toolchain support.

---

To be clear: I'm not asking for Deno to be included in this specific PR. Scoping decisions are completely reasonable — ship npm/bun/yarn/pnpm now. But the framing that Deno is a "new AppHost runtime mode" requiring fundamentally different architecture doesn't hold up when Bun is already treated as an actual runtime in CreateExecuteCommand, Deno 2.7 fully supports the package.json model, and the VS Code debugging concern was solved for Bun by simply reusing the Node.js debugger.

Could you clarify: is there a concrete plan / timeline for Deno toolchain support as a follow-up? The original issue (#15812) mentions both Bun and Deno, and it would be helpful to know if this is "deferred to next sprint" vs. "deferred indefinitely."

[sebastienros]

Could you clarify: is there a concrete plan / timeline for Deno toolchain support as a follow-up?

Not from this PR. This change is intentionally scoped to npm/bun/yarn/pnpm, and I don't want to imply a scheduled Deno follow-up that hasn't actually been committed to.

If we take Deno on, it should happen as a separate issue/PR with an explicit scope decision for the first pass (for example, package.json-based support first vs. a broader Deno-specific workflow/debugging story), rather than trying to fold that into #15812.

[sebastienros]

Could you clarify: is there a concrete plan / timeline for Deno toolchain support as a follow-up?

I split the Deno follow-up into #16218 so the work is tracked separately from #16162.

That issue captures the concrete work items raised here: first-pass scope, toolchain detection/runtime/doctor changes, scaffolding/acquisition questions, debugger decisions, and test coverage. I still don't want to promise a timeline from this PR, but the follow-up is now tracked explicitly.

[davidfowl]

What is this?

[sebastienros]

when testing with a local hive, removing

[github-actions]

🎬 CLI E2E Test Recordings — 74 recordings uploaded (commit a48ffe3)

View recordings

Test	Recording
AddPackageInteractiveWhileAppHostRunningDetached	▶️ View Recording
AddPackageWhileAppHostRunningDetached	▶️ View Recording
AgentCommands_AllHelpOutputs_AreCorrect	▶️ View Recording
AgentInitCommand_DefaultSelection_InstallsSkillOnly	▶️ View Recording
AgentInitCommand_MigratesDeprecatedConfig	▶️ View Recording
AspireAddPackageVersionToDirectoryPackagesProps	▶️ View Recording
AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	▶️ View Recording
Banner_DisplayedOnFirstRun	▶️ View Recording
Banner_DisplayedWithExplicitFlag	▶️ View Recording
Banner_NotDisplayedWithNoLogoFlag	▶️ View Recording
CertificatesClean_RemovesCertificates	▶️ View Recording
CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	▶️ View Recording
CertificatesTrust_WithUntrustedCert_TrustsCertificate	▶️ View Recording
ConfigSetGet_CreatesNestedJsonFormat	▶️ View Recording
CreateAndRunAspireStarterProject	▶️ View Recording
CreateAndRunAspireStarterProjectWithBundle	▶️ View Recording
CreateAndRunEmptyAppHostProject	▶️ View Recording
CreateAndRunJavaEmptyAppHostProject	▶️ View Recording
CreateAndRunJsReactProject	▶️ View Recording
CreateAndRunPythonReactProject	▶️ View Recording
CreateAndRunTypeScriptEmptyAppHostProject	▶️ View Recording
CreateAndRunTypeScriptStarterProject	▶️ View Recording
CreateJavaAppHostWithViteApp	▶️ View Recording
CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	▶️ View Recording
DashboardRunWithOtelTracesReturnsNoTraces	▶️ View Recording
DeployK8sBasicApiService	▶️ View Recording
DeployK8sWithGarnet	▶️ View Recording
DeployK8sWithMongoDB	▶️ View Recording
DeployK8sWithMySql	▶️ View Recording
DeployK8sWithPostgres	▶️ View Recording
DeployK8sWithRabbitMQ	▶️ View Recording
DeployK8sWithRedis	▶️ View Recording
DeployK8sWithSqlServer	▶️ View Recording
DeployK8sWithValkey	▶️ View Recording
DeployTypeScriptAppToKubernetes	▶️ View Recording
DescribeCommandResolvesReplicaNames	▶️ View Recording
DescribeCommandShowsRunningResources	▶️ View Recording
DetachFormatJsonProducesValidJson	▶️ View Recording
DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	▶️ View Recording
DoListStepsShowsPipelineSteps	▶️ View Recording
DoctorCommand_DetectsDeprecatedAgentConfig	▶️ View Recording
DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	▶️ View Recording
DoctorCommand_WithSslCertDir_ShowsTrusted	▶️ View Recording
DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	▶️ View Recording
GlobalMigration_HandlesCommentsAndTrailingCommas	▶️ View Recording
GlobalMigration_HandlesMalformedLegacyJson	▶️ View Recording
GlobalMigration_PreservesAllValueTypes	▶️ View Recording
GlobalMigration_SkipsWhenNewConfigExists	▶️ View Recording
GlobalSettings_MigratedFromLegacyFormat	▶️ View Recording
InitTypeScriptAppHost_AugmentsExistingViteRepoAtRoot	▶️ View Recording
InvalidAppHostPathWithComments_IsHealedOnRun	▶️ View Recording
LegacySettingsMigration_AdjustsRelativeAppHostPath	▶️ View Recording
LogsCommandShowsResourceLogs	▶️ View Recording
OtelLogsReturnsStructuredLogsFromStarterApp	▶️ View Recording
PsCommandListsRunningAppHost	▶️ View Recording
PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
PublishWithConfigureEnvFileUpdatesEnvOutput	▶️ View Recording
PublishWithDockerComposeServiceCallbackSucceeds	▶️ View Recording
PublishWithoutOutputPathUsesAppHostDirectoryDefault	▶️ View Recording
RestoreGeneratesSdkFiles	▶️ View Recording
RestoreGeneratesSdkFiles_WithConfiguredToolchain	▶️ View Recording
RestoreRefreshesGeneratedSdkAfterAddingIntegration	▶️ View Recording
RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	▶️ View Recording
RunFromParentDirectory_UsesExistingConfigNearAppHost	▶️ View Recording
SecretCrudOnDotNetAppHost	▶️ View Recording
SecretCrudOnTypeScriptAppHost	▶️ View Recording
StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	▶️ View Recording
StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	▶️ View Recording
StopAllAppHostsFromAppHostDirectory	▶️ View Recording
StopAllAppHostsFromUnrelatedDirectory	▶️ View Recording
StopNonInteractiveMultipleAppHostsShowsError	▶️ View Recording
StopNonInteractiveSingleAppHost	▶️ View Recording
StopWithNoRunningAppHostExitsSuccessfully	▶️ View Recording
UnAwaitedChainsCompileWithAutoResolvePromises	▶️ View Recording

---

_{📹 Recordings uploaded automatically from CI run #24749185218}

[aspire-repo-bot]

Pull request created: #746

Generated by PR Documentation Check

[aspire-repo-bot]

📝 Documentation PR drafted

A draft documentation PR has been created on microsoft/aspire.dev covering the changes introduced in this PR.

Target branch: main
(Falling back to main because release/13.3 does not yet exist on microsoft/aspire.dev.)

Summary of documentation changes:

• app-host/typescript-apphost.mdx — New "Package manager toolchain" section covering: supported toolchains (npm, pnpm, Yarn, Bun), the auto-detection order (packageManager field → lockfiles → parent directory walk), tabbed declaration examples, a per-toolchain install/run command table, and a mention of the aspire doctor check.
• get-started/prerequisites.mdx — Updated TypeScript AppHost prerequisite to list all supported package managers with install links.
• reference/cli/commands/aspire-doctor.mdx — Updated environment checks description to include JavaScript toolchain validation.

The draft PR needs human review before merging.

Generated by PR Documentation Check for issue #16162 · ● 2M · ◷