TypeScript AppHost project structure

When you create a TypeScript AppHost with aspire new or aspire init --language typescript, the CLI scaffolds a project with the following structure:

• Mappemy-apphost/

  • Mappe.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.json

aspire.config.json

The aspire.config.json file is the central configuration for your AppHost. It replaces the older .aspire/settings.json and apphost.run.json files.

aspire.config.json

{
  "appHost": {
    "path": "apphost.ts",
    "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"
      }
    }
  }
}

Key sections

Section	Description
appHost.path	Path to your AppHost entry point (apphost.ts)
appHost.language	Language runtime (typescript/nodejs)
packages	Hosting integration packages and their versions. Added automatically by aspire add.
profiles	Launch profiles with dashboard URLs and environment variables

Adding integrations

When you run aspire add, the CLI adds the package to the packages section and regenerates the TypeScript SDK:

Add an integration

aspire add redis

This updates aspire.config.json:

aspire.config.json

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

Project references for local development

You can reference a local hosting integration project by using a .csproj path instead of a version:

aspire.config.json

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

See Multi-language integrations for details on building hosting integrations that work with TypeScript AppHosts.

.modules/ directory

The .modules/ directory contains the generated TypeScript SDK. It’s created and updated automatically by the Aspire CLI — do not edit these files.

File	Purpose
aspire.ts	Generated typed API for all your installed integrations
base.ts	Base types and handle infrastructure
transport.ts	JSON-RPC transport layer

The SDK regenerates when:

• You run aspire add to add or update an integration
• You run aspire run or aspire start and the package list has changed
• You run aspire restore to manually regenerate

Your apphost.ts imports from this SDK:

apphost.ts

import { createBuilder } from './.modules/aspire.js';

Tip

Add .modules/ to your .gitignore — it’s generated and can be recreated from aspire.config.json at any time.

apphost.ts

The entry point for your AppHost. This is where you define your application’s resources and their relationships:

apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cache = await builder.addRedis("cache");

const api = await builder
    .addNodeApp("api", "./api", "src/index.ts")
    .withHttpEndpoint({ env: "PORT" })
    .withReference(cache);

await builder.build().run();

Package managers

The Aspire CLI automatically detects which package manager your TypeScript AppHost uses by inspecting lock files and the packageManager field in package.json. The following package managers are supported:

Package manager	Lock file detected	Notes
npm	package-lock.json	Default; no extra setup required
pnpm	pnpm-lock.yaml
Yarn (v4+)	yarn.lock	Must be Yarn 4 or later (Berry)
Bun	bun.lock / bun.lockb

Bemærk

Yarn Classic (v1) is not supported. If the Aspire CLI detects a Yarn Classic lock file (# yarn lockfile v1) or a packageManager field such as "yarn@1.x" in package.json, it throws an error and stops. Upgrade to Yarn 4 or later, or switch to npm, pnpm, or Bun.

To upgrade to Yarn 4, run:

corepack enable yarn
corepack use yarn@stable

package.json

The scaffolded package.json includes convenience scripts and the required Node.js version:

package.json

{
  "name": "my-apphost",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "aspire run",
    "build": "tsc",
    "lint": "eslint apphost.ts"
  },
  "engines": {
    "node": "^20.19.0 || ^22.13.0 || >=24"
  }
}

The dev script means you can also start your AppHost with npm run dev (or the equivalent for your toolchain, for example bun run dev or pnpm run dev).

Package manager toolchain

The Aspire CLI automatically detects which Node-compatible package manager your project uses and adjusts install and run commands accordingly. The following toolchains are supported: npm (default), Bun, Yarn, and pnpm.

Toolchain detection

The CLI resolves the toolchain by inspecting the AppHost directory and its parent directories (up to eight levels). It checks, in order:

1. The packageManager field in package.json — for example, "packageManager": "pnpm@9.0.0".
2. Lockfiles: bun.lock or bun.lockb → Bun; pnpm-lock.yaml → pnpm; yarn.lock, .yarnrc.yml, or a .yarn/ directory → Yarn.
3. If nothing is found, npm is used as the default.

The search walks up parent directories, so a workspace-level packageManager setting or lockfile is picked up automatically by nested AppHosts.

Declaring your toolchain

The recommended way to pin the toolchain is with the packageManager field in package.json, which Aspire uses for toolchain detection. This field is also used by Node.js Corepack for package managers such as Yarn and pnpm:

npm (default)

No extra configuration is required — npm is the default.

pnpm

package.json

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

Yarn

package.json

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

Bun

package.json

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

Alternatively, committing a toolchain-specific lockfile (pnpm-lock.yaml, yarn.lock, bun.lock, etc.) is sufficient for detection.

Install and run commands by toolchain

When a non-npm toolchain is detected, the CLI substitutes the matching commands:

Toolchain	Install command	Execute command	Watch command
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}

Note

Bun has built-in TypeScript support, so it runs apphost.ts directly without tsx.

aspire doctor checks

The aspire doctor command checks that the required JavaScript toolchain executable is available. If Bun, Yarn, or pnpm is detected but not installed, the command reports an error with install guidance.

Aspire CLI

aspire doctor

TypeScript validation before startup

Before starting a TypeScript AppHost, the Aspire CLI runs tsc --noEmit to check for type errors to prevent the dashboard and resources from starting in a partially broken state. If your AppHost has TypeScript compile errors, aspire run and aspire publish stop before the AppHost launches and display the diagnostic output:

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

Watch mode behavior

When you use aspire run in watch mode, the TypeScript validation is embedded in the nodemon restart command. The watcher can still start even if there are initial type errors — it will recover automatically as you edit and save files that fix the errors.

See also

• Build your first app
• AppHost overview
• Multi-language architecture
• aspire doctor command