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:

• Ordnermy-apphost/

  • Ordner.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.2.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.2.0",
    "Aspire.Hosting.Redis": "13.2.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';

Tipp

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.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.

See also

• Build your first app
• AppHost overview
• Multi-language architecture