2026年5月5日に公開または更新されたMicrosoft developer platformのドキュメント更新「Deprecate Aspire.Hosting.NodeJs in CLI integration listings」で、まず確認すべき結論はシンプルです。Aspire CLIでJavaScript/Node.js系の統合を追加する場合、今後はAspire.Hosting.NodeJsではなくAspire.Hosting.JavaScriptを使うべきです。
この変更は、Node.jsそのものが使えなくなるという話ではありません。Aspire.Hosting.NodeJsという古いNuGetパッケージ名がCLIの統合候補から外され、Aspire 13以降のJavaScript/TypeScriptアプリではAspire.Hosting.JavaScriptを使う流れに整理された、という位置づけです。PRでは、Aspire.Hosting.NodeJsを非推奨パッケージのフィルターに追加し、aspire addの結果に表示されないようにする変更が説明されています。(GitHub)
Microsoft developer platformの更新で何が変わったか
今回のMicrosoft developer platformに関する更新では、Aspire CLIの統合パッケージ一覧におけるAspire.Hosting.NodeJsの扱いが変わりました。
公式のAspireドキュメントでは、Aspire 13.0でAspire.Hosting.NodeJsがAspire.Hosting.JavaScriptへリネームされたと説明されています。新規および既存のAspire 13以降のアプリケーションでは、Aspire.Hosting.JavaScriptを使うことが推奨されています。(Aspire)
| 確認項目 | 変更前の見方 | 変更後の見方 |
|---|---|---|
| CLIで追加するパッケージ | Aspire.Hosting.NodeJsを見つけて追加する可能性があった | Aspire.Hosting.JavaScriptを選ぶ |
aspire addの候補 | 古いNodeJsパッケージが候補に出る可能性があった | 非推奨フィルターにより通常の候補から外れる |
| Node.jsアプリの実行 | Node.js向けの統合として理解されやすかった | JavaScript/TypeScript全体を扱う統合として整理される |
| 既存プロジェクト | 古いパッケージ参照が残っている可能性がある | 参照・手順・CI設定を確認する |
重要なのは、非推奨になったのはNode.jsランタイムではなく、Aspire.Hosting.NodeJsというパッケージ名だという点です。AspireのJavaScript統合は、Node.jsランタイム、npm、yarn、pnpm、bun、Viteなどを含むJavaScript/TypeScriptアプリのオーケストレーションを扱うものとして説明されています。(Aspire)
Aspire.Hosting.NodeJsはなぜAspire.Hosting.JavaScriptへ置き換わるのか
Aspire.Hosting.NodeJsという名前は、対象がNode.jsだけに見えやすい名称です。しかし、現在のAspireではJavaScript/TypeScriptアプリケーション全体を扱う方向に整理されています。
たとえば、フロントエンドがVite、APIがExpress、パッケージ管理がpnpmという構成でも、開発者が意識する対象は「Node.js単体」ではなく「JavaScript/TypeScriptアプリ」です。そのため、Aspire.Hosting.JavaScriptという名前のほうが実態に合っています。
Aspire 13.0では、JavaScriptとPythonが「first-class citizens」として扱われ、Aspireは.NET中心のオーケストレーションツールからマルチランゲージなアプリケーションプラットフォームへ位置づけが広がっています。(Aspire)
影響を受ける人と受けにくい人
今回のMicrosoft developer platform documentation updateは、すべての開発者に即時対応を求めるものではありません。ただし、Aspire CLIやNuGetパッケージ参照を使っているチームは確認しておくべきです。
| 対象 | 影響度 | 確認すべきこと |
|---|---|---|
| Aspire CLIでJavaScript統合を追加している人 | 高 | aspire add javascriptを使う手順になっているか |
Aspire.Hosting.NodeJsを既存AppHostで参照しているプロジェクト | 高 | Aspire.Hosting.JavaScriptへ置き換える計画が必要 |
| チーム内ドキュメントやREADMEに旧パッケージ名を書いているチーム | 中 | 手順が古いまま残っていないか |
| CI/CDでNuGetパッケージ名を固定しているチーム | 中 | Directory.Packages.propsや.csprojを確認する |
| Node.jsアプリを単体で運用しておりAspireを使っていない人 | 低 | 直接の影響は小さい |
| Community ToolkitのNode.js拡張を使っている人 | 中 | 本体パッケージとの役割を混同していないか |
特に注意したいのは、CLIの候補に出なくなったからといって、既存コードが自動的に書き換わるわけではないことです。.csproj、Directory.Packages.props、AppHostのファイル、社内手順書、テンプレートリポジトリを別々に確認する必要があります。
新規追加ではaspire add javascriptを使う
新しくAspireのAppHostにJavaScript/TypeScriptアプリを追加する場合は、Aspire.Hosting.JavaScriptを前提にします。公式ドキュメントでは、Aspire CLIで次のコマンドを使う例が示されています。(Aspire)
aspire add javascriptCLIの対話画面では、次のようにAspire.Hosting.JavaScriptが選択対象として表示されます。
Select an integration to add:
> javascript (Aspire.Hosting.JavaScript).csprojに直接追加する場合は、AppHostプロジェクト側で次のようなPackageReferenceを確認します。
<PackageReference Include="Aspire.Hosting.JavaScript" Version="*" />C#のfile-based app形式では、次のようなパッケージ指定が使われます。
#:package Aspire.Hosting.JavaScript@*実務ではVersion="*"のままにするか、チームの運用に合わせて明示的なバージョン管理にするかを決めてください。本番運用やCIで再現性を重視する場合は、Central Package Managementを使い、Directory.Packages.propsでバージョンを管理するほうが安全です。
既存プロジェクトで確認するべき場所
既存プロジェクトでは、まず旧パッケージ名が残っていないかを確認します。単にAppHostの.csprojだけを見るのではなく、リポジトリ全体を検索するのが確実です。
Windows PowerShellで検索する
Select-String -Path .\* -Pattern "Aspire.Hosting.NodeJs" -RecursemacOS/Linux/Git Bashで検索する
grep -R "Aspire.Hosting.NodeJs" .確認対象は主に次のファイルです。
| 確認場所 | 見るべき内容 |
|---|---|
AppHostの.csproj | PackageReference Include="Aspire.Hosting.NodeJs"が残っていないか |
Directory.Packages.props | PackageVersion Include="Aspire.Hosting.NodeJs"が残っていないか |
AppHost.csやfile-based app | #:package Aspire.Hosting.NodeJs@...が残っていないか |
| README・セットアップ手順 | aspire addの説明が古くないか |
| CI/CD設定 | dotnet add package Aspire.Hosting.NodeJsなどの固定手順がないか |
| テンプレートリポジトリ | 新規作成時に旧パッケージを入れていないか |
検索結果が出た場合は、原則としてAspire.Hosting.JavaScriptへの置き換えを検討します。
移行の基本手順
移行は大きく分けて、パッケージ参照の置き換え、ビルド確認、アプリ起動確認の3段階で進めます。
| 手順 | 作業内容 | 失敗しやすいポイント |
|---|---|---|
| 1 | 旧パッケージ参照を検索する | .csprojだけ見てREADMEやCPMを見落とす |
| 2 | Aspire.Hosting.JavaScriptへ置き換える | バージョン管理方式を統一しない |
| 3 | dotnet restoreを実行する | NuGetキャッシュやロックファイルの差分を確認しない |
| 4 | AppHostをビルドする | usingや拡張メソッドの差分をビルドエラーで確認しない |
| 5 | aspire runなどで起動確認する | フロントエンドのdev scriptやポート設定を見落とす |
| 6 | チーム手順書を更新する | コードだけ直してオンボーディング手順が古いまま残る |
たとえば、AppHostプロジェクトで旧パッケージを直接参照している場合は、次のような流れで確認できます。
dotnet remove package Aspire.Hosting.NodeJs
dotnet add package Aspire.Hosting.JavaScript
dotnet restore
dotnet buildCentral Package Managementを使っている場合は、コマンドだけで完結しないことがあります。Directory.Packages.propsの該当行を手で確認してください。
<!-- 旧 -->
<PackageVersion Include="Aspire.Hosting.NodeJs" Version="..." />
<!-- 新 -->
<PackageVersion Include="Aspire.Hosting.JavaScript" Version="..." />バージョン番号は、プロジェクトで使っているAspire本体や他のAspire関連パッケージとそろえるのが基本です。複数のAspireパッケージだけバージョンがばらつくと、復元やビルドで原因の分かりにくいエラーにつながります。
AddJavaScriptApp、AddNodeApp、AddViteAppの使い分け
Aspire.Hosting.JavaScriptは、単にパッケージ名が変わっただけでなく、JavaScript/TypeScriptアプリを用途に応じて扱いやすくする統合として説明されています。公式ドキュメントでは、JavaScriptAppResource、NodeAppResource、ViteAppResourceなどのリソース種別が紹介されています。(Aspire)
使い分けの考え方は次のとおりです。
| 用途 | 選び方の目安 |
|---|---|
| 一般的なJavaScriptアプリをAppHostに追加したい | AddJavaScriptAppを中心に考える |
| 特定のJavaScriptファイルをNode.jsで実行したい | AddNodeAppが合う可能性がある |
| Viteベースのフロントエンドを扱いたい | AddViteAppが合う可能性がある |
| yarnやpnpmの専用拡張を使いたい | Community ToolkitのNode.js extensionsも確認する |
ここで大事なのは、パッケージ名はJavaScriptでも、Node.jsアプリが対象外になったわけではないという点です。Node.jsランタイムを含むJavaScript/TypeScriptアプリの扱いが、より広い名称に整理されたと理解すると誤解しにくくなります。
Community ToolkitのNode.js extensionsと混同しない
今回の変更で混同しやすいのが、CommunityToolkit.Aspire.Hosting.NodeJS.Extensionsです。
公式ドキュメントでは、このCommunity ToolkitのNode.js hosting extensionsは、Aspire.Hosting.JavaScriptに追加機能を提供するパッケージとして説明されています。たとえば、Viteアプリの実行、Yarnやpnpmを使ったNode.jsアプリの実行、パッケージインストールの確認などが挙げられています。(Aspire)
つまり、次のように整理できます。
| パッケージ | 役割 |
|---|---|
Aspire.Hosting.JavaScript | Aspire 13以降で基本となるJavaScript/TypeScript hosting integration |
Aspire.Hosting.NodeJs | 旧名称。新規・既存のAspire 13以降では置き換え対象 |
CommunityToolkit.Aspire.Hosting.NodeJS.Extensions | JavaScript統合に追加機能を足すCommunity Toolkitの拡張 |
「NodeJS」という文字列が含まれるからすべて非推奨、という判断は危険です。今回の対象は、主にAspire.Hosting.NodeJsという旧パッケージ名です。Community Toolkitの拡張を使っている場合は、そのドキュメントに沿って役割を確認してください。
CLIで旧パッケージが出ない場合の見方
aspire addでAspire.Hosting.NodeJsが見つからない場合、それは異常ではありません。今回の更新では、旧パッケージを非推奨パッケージのフィルターに追加し、CLIの統合候補に表示されないようにする変更が行われています。(GitHub)
そのため、次のような判断をしてください。
| 状況 | 判断 |
|---|---|
aspire addでAspire.Hosting.NodeJsが出ない | 正常。aspire add javascriptを使う |
社内手順書にAspire.Hosting.NodeJsが書かれている | 手順書を更新する |
| 既存プロジェクトで旧パッケージが復元されている | すぐ壊れるとは限らないが、置き換え計画を立てる |
| 新旧パッケージが両方入っている | 依存関係が分かりにくくなるため整理する |
| 古いCLIでは旧候補が出る | CLI更新後の挙動を確認する |
Aspire 13.2のアップグレード手順では、CLIの更新にaspire update --self、AppHost側の更新にaspire updateを使う流れが紹介されています。ただしaspire updateはプレビュー扱いとされているため、実行前に差分確認しやすい状態で作業するのが安全です。(Aspire)
チームで対応する場合の実務チェックリスト
個人開発ならパッケージ名を置き換えてビルド確認すれば十分なこともあります。一方、チーム開発では「誰かのローカルでは動くが、新規参加者やCIで失敗する」パターンが起きやすいため、確認範囲を広げるべきです。
コードと依存関係の確認
まず、リポジトリ内の参照を確認します。
grep -R "Aspire.Hosting.NodeJs" .
grep -R "aspire add" .
grep -R "nodejs" .Windows中心のチームなら、PowerShellで同様に検索できます。
Select-String -Path .\* -Pattern "Aspire.Hosting.NodeJs","aspire add","nodejs" -Recurse検索対象には、ソースコードだけでなく次のファイルも含めてください。
README.mddocs/配下の開発手順.github/workflows/などのCI設定Directory.Packages.propsglobal.json- DockerfileやDev Container設定
- 社内テンプレートの作成スクリプト
CIで確認するコマンド
移行後は、最低限次の流れで確認します。
dotnet restore
dotnet buildAspire AppHostを起動できる環境なら、次も確認します。
aspire runJavaScript/TypeScript側では、package.jsonのscriptも確認してください。Aspire側のパッケージ名を直しても、フロントエンド側のdevやbuildが壊れているとAppHost起動時に失敗します。
{
"scripts": {
"dev": "vite",
"build": "vite build"
}
}AddJavaScriptAppでは、package.jsonがある場合にnpmを使い、ローカル開発ではdev、公開時にはbuildスクリプトを使う動きが説明されています。(Aspire)
失敗しやすいポイント
今回の更新は見た目より小さな変更に見えますが、実務ではいくつか落とし穴があります。
Node.js自体が非推奨になったと誤解する
もっとも多い誤解は、「Node.jsがAspireで非推奨になった」と受け取ってしまうことです。
実際には、Aspire.Hosting.NodeJsという旧パッケージ名が非推奨扱いになり、Aspire.Hosting.JavaScriptへ移る話です。JavaScript/TypeScriptアプリやNode.jsランタイムの利用をやめる必要がある、という意味ではありません。
CLI候補だけ見て既存参照を放置する
aspire addの候補から旧パッケージが消えても、既存プロジェクトのPackageReferenceが自動的に消えるとは限りません。
特に、次のような状態は後から混乱を招きます。
<PackageReference Include="Aspire.Hosting.NodeJs" Version="..." />
<PackageReference Include="Aspire.Hosting.JavaScript" Version="..." />新旧パッケージが両方ある場合は、なぜ両方必要なのかを確認し、不要な参照を整理してください。
チームのオンボーディング手順が古いまま残る
新しいメンバーがREADMEを見てAspire.Hosting.NodeJsを追加しようとしても、CLIの候補に出ず、そこで詰まる可能性があります。
コード修正だけでなく、次のような説明も更新しておきましょう。
古い手順:
aspire add nodejs
新しい手順:
aspire add javascript実際のCLIコマンド名や候補名はバージョンによって変わる可能性があるため、社内手順では「Aspire.Hosting.JavaScriptを選択する」と明記しておくと安全です。
Community Toolkitの拡張まで消してしまう
NodeJSという文字列だけを見て、CommunityToolkit.Aspire.Hosting.NodeJS.Extensionsまで削除してしまうのも危険です。
Community ToolkitのNode.js extensionsは、Aspire.Hosting.JavaScriptに追加機能を提供する別のパッケージです。Yarn、pnpm、Vite関連の拡張を使っている場合は、削除前に実際の利用箇所を確認してください。(Aspire)
移行判断の目安
すぐに置き換えるべきか、次のリリースサイクルで対応すべきかは、プロジェクトの状況で判断できます。
| プロジェクト状況 | 推奨対応 |
|---|---|
| 新規にAspire 13以降で作る | 最初からAspire.Hosting.JavaScriptを使う |
既存でAspire.Hosting.NodeJsを使っているが動作は安定している | 次の依存関係更新タイミングで置き換える |
| CLI手順やテンプレートを社内配布している | 早めに更新する |
CIでdotnet add package Aspire.Hosting.NodeJsしている | 優先して修正する |
| Vite、pnpm、Yarnの拡張を使っている | Community Toolkitとの関係を確認してから修正する |
| Aspireのメジャーバージョン更新も同時に行う | 変更点が増えるため、パッケージ置換とバージョン更新を分けて検証する |
迷った場合は、まず検索だけ実施してください。Aspire.Hosting.NodeJsがリポジトリ内に存在しなければ、今回の変更による直接対応はほぼ不要です。存在する場合は、置き換え対象を一覧化し、ビルドと起動確認まで進めるのが現実的です。
管理者・リードエンジニアが見るべき観点
チームや組織でMicrosoft developer platformを利用している場合、単なるパッケージ名変更として片付けず、開発者体験の観点で確認すると効果的です。
特に見るべきポイントは次の3つです。
1つ目は、開発環境の再現性です。
新規メンバーが手順どおりにaspire addしても旧パッケージが出ないなら、オンボーディングの最初でつまずきます。READMEやセットアップスクリプトを更新してください。
2つ目は、依存関係の一貫性です。
Aspire関連パッケージのバージョンが混在していると、ビルドや復元の失敗原因を追いにくくなります。AppHost側のAspireパッケージ群は、できるだけ同じ更新サイクルで管理するのがおすすめです。
3つ目は、名称変更の意図をチームに共有することです。NodeJsからJavaScriptへの変更は、単なる表記変更ではなく、AspireがJavaScript/TypeScriptアプリ全体を扱う方向に整理されたことを示しています。フロントエンド、API、BFF、ワーカープロセスなどをAppHostでまとめて扱うチームほど、この理解が重要になります。
今回の更新で取るべき次の行動
今回のMicrosoft developer platform documentation updateでは、Aspire.Hosting.NodeJsがCLIの統合候補から外れ、置き換え先としてAspire.Hosting.JavaScriptを使う方針が明確になりました。
対応は次の順で進めると安全です。
- リポジトリ全体で
Aspire.Hosting.NodeJsを検索する - 見つかった場合は
Aspire.Hosting.JavaScriptへ置き換える .csproj、Directory.Packages.props、AppHost、README、CI設定を確認するdotnet restore、dotnet build、必要に応じてaspire runで検証する- 新規追加手順を
aspire add javascriptベースに更新する
この変更は、急にNode.jsアプリが使えなくなるような更新ではありません。ただし、旧パッケージ名を前提にした手順やテンプレートは、今後のAspire CLIの利用でつまずきやすくなります。新規プロジェクトではAspire.Hosting.JavaScriptを標準にし、既存プロジェクトでは依存関係更新のタイミングで計画的に置き換えるのが現実的です。
コメント