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:

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.

{
  "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:

aspire add redis

This updates 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:

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

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

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:

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:

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