TypeScript AppHost プロジェクト構造

aspire new で TypeScript AppHost を作成すると、CLI は以下の構造でプロジェクトをスキャフォルドします：

ディレクトリmy-apphost/
- ディレクトリ.aspire/modules/ 生成された TypeScript SDK（編集しないでください）
  - aspire.mts
  - base.mts
  - transport.mts
- apphost.mts AppHost エントリポイント
- aspire.config.json Aspire 設定
- package.json
- tsconfig.apphost.json

ルートに既存の package.json がある JavaScript または TypeScript アプリで aspire init --language typescript を実行すると、Aspire は AppHost をネストされた aspire-apphost/ パッケージに作成します。ルートの aspire.config.json は aspire-apphost/apphost.mts を指し、ルートの package.json には Aspire 委譲スクリプトが追加されます：

ディレクトリmy-existing-app/
- ディレクトリaspire-apphost/
  - ディレクトリ.aspire/modules/ 生成された TypeScript SDK（編集しないでください）
    aspire.mts
    base.mts
    transport.mts
  - apphost.mts AppHost エントリポイント
  - package.json
  - tsconfig.apphost.json
- aspire.config.json Aspire 設定
- package.json Aspire 委譲スクリプトを含む既存アプリパッケージ

aspire.config.json

aspire.config.json ファイルは AppHost にとって中核となる設定ファイルです。古い .aspire/settings.json と apphost.run.json ファイルに代わります。

{
  "appHost": {
    "path": "apphost.mts",
    "language": "typescript/nodejs"
  },
  "packages": {
    "Aspire.Hosting.JavaScript": "13.3.0"
  },
  "profiles": {
    "https": {
      "applicationUrl": "https://localhost:17127;http://localhost:15118",
      "environmentVariables": {
        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21169",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22260"
      }
    }
  }
}

主要セクション

セクション	説明
`appHost.path`	AppHost エントリポイント（`apphost.mts`）へのパス
`appHost.language`	言語ランタイム（`typescript/nodejs`）
`packages`	ホスティング統合パッケージとそのバージョン。`aspire add` で自動的に追加されます。
`profiles`	ダッシュボード URL と環境変数を含むローンチプロファイル

統合の追加

aspire add を実行すると、CLI はパッケージを packages セクションに追加し、TypeScript SDK を再生成します：

aspire add redis

これにより aspire.config.json が更新されます：

{
  "packages": {
    "Aspire.Hosting.JavaScript": "13.3.0",
    "Aspire.Hosting.Redis": "13.3.0"
  }
}

ローカル開発用のプロジェクト参照

バージョンの代わりに .csproj パスを使用することで、ローカルホスティング統合プロジェクトを参照できます：

{
  "packages": {
    "MyIntegration": "../src/MyIntegration/MyIntegration.csproj"
  }
}

詳細については、マルチ言語統合を参照してください。

.aspire/modules/ ディレクトリ

AppHost ルートの .aspire/modules/ ディレクトリには、生成された TypeScript SDK が含まれます。Aspire CLI によって自動的に作成および更新されます。これらのファイルは編集しないでください。

ファイル	目的
`aspire.mts`	インストール済みのすべての統合用に生成された型付け API
`base.mts`	基本型とハンドルインフラストラクチャ
`transport.mts`	JSON-RPC トランスポート層

SDK は以下の場合に再生成されます：

aspire add を実行して統合を追加または更新した場合
aspire run または aspire start を実行し、パッケージリストが変更されている場合
aspire restore を実行して手動で再生成した場合

apphost.mts はこの SDK からインポートします：

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

apphost.mts

AppHost のエントリポイント。ここでアプリケーションのリソースとそれらの関係を定義します：

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const cache: RedisResource
cache = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addRedis(name: string, options?: {
    port?: number;
    password?: string | ParameterResource;
}): RedisResource (+1 overload)
Adds a Redis container to the application model.
addRedis("cache");

const 
const api: NodeAppResource
api = await 
const builder: IDistributedApplicationBuilder
builder
    .
IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "src/index.ts")
    .
ExecutableResource.withHttpEndpoint(options?: {
    port?: number;
    targetPort?: number;
    name?: string;
    env?: string;
    isProxied?: boolean;
} | undefined): NodeAppResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ 
env?: string | undefined
env: "PORT" })
    .
ExecutableResource.withReference(source: EndpointReference | string | uri, options?: {
    connectionName?: string;
    optional?: boolean;
    name?: string;
} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(
const cache: RedisResource
cache);

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

パッケージマネージャー

Aspire CLI はロックファイルと package.json の packageManager フィールドを調べることで、TypeScript AppHost が使用するパッケージマネージャーを自動的に検出します。以下のパッケージマネージャーがサポートされています：

パッケージマネージャー	検出されるロックファイル	注
npm	`package-lock.json`	デフォルト。追加のセットアップは不要です
pnpm	`pnpm-lock.yaml`
Yarn (v4+)	`yarn.lock`	Yarn 4 以降（Berry）である必要があります
Bun	`bun.lock` / `bun.lockb`

Yarn Classic (v1) はサポートされていません。 Aspire CLI が Yarn Classic ロックファイル（# yarn lockfile v1）または package.json の "yarn@1.x" などの packageManager フィールドを検出した場合、エラーをスローして停止します。Yarn 4 以降にアップグレードするか、npm、pnpm、または Bun に切り替えてください。

Yarn 4 にアップグレードするには、以下を実行します：

corepack enable yarn
corepack use yarn@stable

package.json

スキャフォルドされた package.json は便利なスクリプトと必要な Node.js バージョンを含みます：

{
  "name": "my-apphost",
  "private": true,
  "type": "module",
  "scripts": {
    "aspire:lint": "eslint apphost.mts",
    "aspire:start": "aspire run",
    "aspire:build": "tsc -p tsconfig.apphost.json",
    "aspire:dev": "tsc --watch -p tsconfig.apphost.json",
    "lint": "npm run aspire:lint",
    "dev": "npm run aspire:start",
    "build": "npm run aspire:build",
    "watch": "npm run aspire:dev"
  },
  "engines": {
    "node": "^20.19.0 || ^22.13.0 || >=24"
  }
}

dev スクリプトは npm run dev で AppHost を起動することもできます（または、ツールチェーンと同等のもの、例えば bun run dev または pnpm run dev）。

パッケージマネージャーツールチェーン

Aspire CLI はプロジェクトが使用する Node 互換パッケージマネージャーを自動的に検出し、インストールコマンドと実行コマンドを調整します。以下のツールチェーンがサポートされています：npm（デフォルト）、Bun、Yarn、および pnpm。

ツールチェーン検出

CLI は AppHost ディレクトリと親ディレクトリ（最大 8 レベル）を検査してツールチェーンを解決します。以下の順序で確認します：

package.json の packageManager フィールド（例："packageManager": "pnpm@9.0.0"）。
ロックファイル：bun.lock または bun.lockb → Bun、pnpm-lock.yaml → pnpm、yarn.lock、.yarnrc.yml、または .yarn/ ディレクトリ → Yarn。
何も見つからない場合、npm がデフォルトとして使用されます。

検索は親ディレクトリを走査するため、ワークスペースレベルの packageManager 設定またはロックファイルはネストされた AppHost によって自動的に取得されます。

ツールチェーンの宣言

ツールチェーンをピン留めするための推奨方法は、package.json の packageManager フィールドです。Aspire がツールチェーン検出に使用します。このフィールドは、Yarn や pnpm などのパッケージマネージャーの Node.js Corepack でも使用されます：

追加の設定は不要です。npm がデフォルトです。

{
  "packageManager": "pnpm@9.0.0",
  "name": "my-apphost",
  "private": true,
  "type": "module"
}

{
  "packageManager": "yarn@4.0.0",
  "name": "my-apphost",
  "private": true,
  "type": "module"
}

{
  "packageManager": "bun@1.1.0",
  "name": "my-apphost",
  "private": true,
  "type": "module"
}

別の方法として、ツールチェーン固有のロックファイル（pnpm-lock.yaml、yarn.lock、bun.lock など）をコミットするだけで、検出に十分です。

ツールチェーン別のインストールおよび実行コマンド

npm 以外のツールチェーンが検出されると、CLI は一致するコマンドを置き換えます：

ツールチェーン	インストールコマンド	実行コマンド	ウォッチコマンド
npm	`npm install`	`npx tsx ...`	`npx nodemon ...`
pnpm	`pnpm install`	`pnpm exec tsx ...`	`pnpm exec nodemon ...`
Yarn	`yarn install`	`yarn exec tsx ...`	`yarn exec nodemon ...`
Bun	`bun install`	`bun run {appHostFile}`	`bun --watch run {appHostFile}`

aspire doctor チェック

aspire doctor コマンドは、必要な JavaScript ツールチェーン実行可能ファイルが利用可能かどうかを確認します。Bun、Yarn、または pnpm が検出されているが、インストールされていない場合、コマンドはインストールガイダンスでエラーを報告します。

aspire doctor

スタートアップ前の TypeScript 検証

TypeScript AppHost を開始する前に、Aspire CLI は tsc --noEmit を実行して型エラーをチェックし、ダッシュボードとリソースが部分的に壊れた状態で開始されるのを防ぎます。AppHost に TypeScript コンパイルエラーがある場合、aspire run と aspire publish は AppHost が起動する前に停止し、診断出力を表示します：

apphost.mts(22,7): error TS2322: Type 'string' is not assignable to type 'number'.

ウォッチモード動作

ウォッチモードで aspire run を使用する場合、TypeScript 検証は nodemon 再起動コマンドに組み込まれます。ウォッチャーは、初期の型エラーがあっても開始できます。エラーを修正するファイルを編集して保存すると、自動的に回復します。