Aspireify an existing app with a TypeScript AppHost

This guide shows you how to add Aspire orchestration to an existing JavaScript or TypeScript application while using a TypeScript AppHost (apphost.ts). You'll initialize Aspire with aspire init --language typescript, model your resources in apphost.ts, and run the app locally with Aspire.

[!NOTE] Definition Aspireify (verb): To transform an existing application into a distributed, observable, and orchestrated system by adding Aspire—no cape required, just a few commands!

Why add Aspire to an existing app?

As distributed applications grow, coordinating multiple services becomes a tangled web of configuration files, hard-coded URLs, and fragile startup scripts. You're juggling connection strings across environments, manually wiring service dependencies, and struggling to trace issues across your microservices. Development setup becomes a ritual of precision—start the database, then the cache, then service A before service B—and any misstep sends you back to square one.

Aspire cuts through this complexity with a unified orchestration layer that treats your entire application as a cohesive system. Define your services and their relationships once in code (the AppHost), and Aspire handles service discovery, injects configuration automatically, and provides a dashboard with logs, traces, and metrics out of the box. When you're orchestrating JavaScript and TypeScript services, you get the same consistent experience from development through deployment.

The best part? You can adopt Aspire incrementally. Start with orchestration, add observability when you're ready, integrate external services as needed. Your existing codebase stays largely unchanged, and you can reverse course if Aspire isn't the right fit.

Prerequisites

Before you begin, ensure you have the following prerequisites installed:

Common requirements

• Aspire CLI installed — For orchestration and deployment commands.
• An existing application to add Aspire to.

Language-specific requirements

For JavaScript/TypeScript applications:

• Node.js 22 or later installed
• npm, yarn, or pnpm for package management
• An existing JavaScript/TypeScript application

Example application types:

• React, Vue, or Svelte applications (especially Vite-based)
• Node.js/Express APIs
• Next.js applications
• Angular applications
• TypeScript backend services

[!TIP] Multi-language applications If your application uses multiple languages, ensure you have all the relevant prerequisites installed. The Aspire AppHost can orchestrate services across different languages simultaneously.

Overview of the process

Adding Aspire to an existing application follows these key steps:

Initialize Aspire support

The aspire init command is the starting point for adding Aspire to your existing application. It adds an AppHost that orchestrates your services while letting those services stay in their current languages.

What does aspire init create?

After running aspire init --language typescript, your project will have a TypeScript AppHost:

A typical monorepo with Node.js API, React storefront, and admin dashboard.

[!NOTE] The .modules folder is generated The .modules/ folder contains generated AppHost SDK files. Let the Aspire CLI manage it rather than editing those files manually.

The apphost.ts file initially contains a minimal starter:

// Aspire TypeScript AppHost
// For more information, see: https://aspire.dev
  
  
const builder = await createBuilder();
  
// Add your resources here, for example:
// const redis = await builder.addContainer("cache", "redis:latest");
// const postgres = await builder.addPostgres("db");
  
await builder.build().run();

This is your starting point. In the next section, you'll add your applications and configure their relationships.

Add your applications to the AppHost

Once you have an AppHost, you need to register your existing applications. First, install the appropriate hosting packages for your application types, then add your resources to the AppHost.

Install hosting packages

For JavaScript/TypeScript applications, add the JavaScript hosting integration to your AppHost:

aspire add javascript

This updates the generated AppHost SDK with methods like addViteApp, addNodeApp, and addJavaScriptApp.

Model your resources in the AppHost

Now update your apphost.ts file to register your applications as resources. Resources are the building blocks of your distributed application—each service, container, or infrastructure resource becomes something Aspire can orchestrate.

For JavaScript applications, use the appropriate method based on your application type:

const builder = await createBuilder();
  
// Node.js API
const api = await builder
  .addNodeApp('api', './packages/api', 'src/server.js')
  .withNpm()
  .withHttpHealthCheck({ path: '/health' });
  
// React storefront
const web = await builder
  .addViteApp('web', './packages/web')
  .withExternalHttpEndpoints()
  .withReference(api)
  .waitFor(api);
  
// Admin dashboard
const admin = await builder
  .addViteApp('admin', './packages/admin')
  .withExternalHttpEndpoints()
  .withReference(api)
  .waitFor(api);
  
await builder.build().run();

Key methods:

• addViteApp - For Vite-based applications (React, Vue, Svelte)
• addNodeApp - For Node.js applications
• addJavaScriptApp - For generic JavaScript applications with npm/yarn/pnpm
  • withNpm() / withYarn() / withPnpm() - Specify package manager
• withRunScript - Specify which npm script to run during development

[!CAUTION] JavaScript deployment note This example shows how to run existing JavaScript applications with Aspire during development. It does not, by itself, define who serves a Vite or JavaScript frontend in production.

If you plan to publish or deploy these frontend resources, read Deploy JavaScript apps to choose the correct production hosting model.

[!NOTE] Passing arguments to scripts Pass arguments to your scripts in one of two ways:

Option 1: Use withArgs to pass arguments directly

await builder.addViteApp('frontend', './frontend').withArgs(['--no-open']);

Option 2: Define custom scripts in package.json with arguments

{
  "scripts": {
    "dev": "vite",
    "dev:no-open": "vite --no-open"
  }
}

await builder.addViteApp('frontend', './frontend').withRunScript('dev:no-open');

Option 2 keeps all script configuration in package.json, making your scripts more discoverable and easier to run outside of Aspire (e.g., npm run dev:no-open).

Connect services

The withReference calls establish service dependencies and enable service discovery:

// Omitted for brevity...
  
const api = await builder
  .addNodeApp('api', '../node-api', 'server.js')
  .withNpm();
  
await builder.addViteApp('frontend', '../react-frontend').withReference(api); // Frontend gets API_HTTP and API_HTTPS env vars
  
// Omitted for brevity...

When you call withReference, you're declaring a dependency between resources. Aspire handles the rest—automatically injecting configuration at runtime and during deployment so your services can communicate seamlessly, whether running locally or in production.

Add telemetry configuration (optional)

TypeScript Node.js applications can also send telemetry using OpenTelemetry. The example below uses TypeScript and ESM imports so it fits naturally into a TypeScript codebase. If your app uses plain JavaScript, keep the same structure but use .js files and your existing module syntax.

Add integrations (optional)

Aspire provides integration libraries that simplify working with common services like Redis, PostgreSQL, RabbitMQ, and more. These integrations handle configuration, health checks, and telemetry automatically.

When you add a hosting integration (like Redis) to your AppHost and reference it from a dependent resource, Aspire automatically injects the necessary configuration. This includes connection strings, URLs, environment variables, and other service-specific settings—eliminating manual connection string management across your services.

Run and verify

Now that you've added Aspire to your application, it's time to run it and see the orchestration in action.

Compare with Docker Compose

If you're currently using Docker Compose, the example below shows how the same relationships translate into a TypeScript AppHost:

Docker Compose approach

services:
   postgres:
      image: postgres:latest
      environment:
         - POSTGRES_PASSWORD=postgres
         - POSTGRES_DB=mydb
      ports:
         - "5432:5432"
  
   api:
      build: ./api
      ports:
         - "8080:8080"
      environment:
         - DATABASE_URL=postgres://postgres:postgres@postgres:5432/mydb
      depends_on:
         - postgres
  
   web:
      build: ./web
      ports:
         - "3000:3000"
      environment:
         - API_URL=http://api:8080
      depends_on:
         - api

Aspire's approach

const builder = await createBuilder();
  
const db = (await builder.addPostgres('postgres')).addDatabase('mydb');
  
const api = await builder
  .addNodeApp('api', './api', 'server.js')
  .withNpm()
  .withReference(db);
  
await builder
  .addViteApp('web', './web')
  .withExternalHttpEndpoints()
  .withReference(api)
  .waitFor(api);
  
await builder.build().run();

The orchestration pattern stays the same: model the shared dependencies once, then connect services with withReference.

Key advantages of Aspire over Docker Compose:

• No manual URL configuration — Services discover each other automatically.
• Code-based resource references — Define service dependencies in code instead of duplicating them in YAML.
• Built-in dashboard — Observability without additional tools like Prometheus/Grafana.
• Reusable orchestration code — The same AppHost definitions work locally and can also drive deployment targets.
• Integration libraries — Pre-built support for databases, caches, message queues with best practices.

Next steps

Congratulations! You've successfully added Aspire to your existing application. Here are some recommended next steps:

• Add more integrations — Explore Aspire integrations to simplify working with databases, caches, and message queues

• Configure observability — Enhance your application's telemetry:

  • See Standalone dashboard for Node.js

• Deploy your app — Follow the Deploy your first app tutorial to deploy your Aspire application

• Use the VS Code extension — Run, debug, and manage integrations from within VS Code with the Aspire extension

• Explore the dashboard — Learn more about the Aspire dashboard and its features

• Learn about JavaScript support — See JavaScript support in Aspire