Polyglot AppHost

Preview feature

Aspire’s polyglot support allows you to write AppHosts in TypeScript instead of C#. This enables teams to use TypeScript while still benefiting from Aspire’s orchestration capabilities, including access to 40+ hosting integrations (Redis, PostgreSQL, Azure services, and more).

Polyglot AppHost support is currently in preview. Not all features are supported, and the API may change.

To enable this feature, run the following command:

aspire config set features:polyglotSupportEnabled true --global

For more information, see aspire config command reference

How it works

When you create a polyglot AppHost:

The Aspire CLI scaffolds a TypeScript AppHost project
A .NET AppHost Server runs in the background, handling orchestration
Your code communicates with the server via JSON-RPC over Unix sockets (or named pipes on Windows)
The server manages containers, service discovery, and the Aspire Dashboard

flowchart LR
    subgraph YourCode["Your Code"]
        TS["TypeScript AppHost"]
    end

    subgraph Server[".NET AppHost Server"]
        RPC["JSON-RPC"]
        ORCH["Orchestration"]
        SD["Service Discovery"]
    end

    subgraph Resources["Managed Resources"]
        DASH["Aspire Dashboard"]
        CONT["Containers"]
        INT["140+ Integrations"]
    end

    TS --> RPC
    RPC --> ORCH
    ORCH --> SD
    SD --> DASH & CONT & INT

This architecture gives you access to the full power of Aspire’s orchestration while writing code in TypeScript.

Prerequisites

Before creating a polyglot AppHost, ensure you have the following installed:

Requirement	Version	Notes
.NET SDK	10.0+	Required for the AppHost server
Aspire CLI	Latest	Install using the install script
Docker	Latest	Required for container resources
Node.js	20+	LTS version recommended
npm or pnpm	Latest	Package manager

Create an AppHost

The following steps demonstrate how to create a new TypeScript AppHost.

Create and initialize the AppHost:
Initialize TypeScript AppHost
```
aspire new -l typescript --name my-apphost
```
Tip
You can also initialize a TypeScript AppHost in an existing directory:
Initialize in existing directory
mkdir my-apphost && cd my-apphost aspire init -l typescript
The following project structure is created:
- Directorymy-apphost/ - .aspire/ - settings.json - .modules/ Generated SDK (created on first run) - apphost.ts Your AppHost code - apphost.run.json - package.json - tsconfig.json
  - …

Review the generated apphost.ts:

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

const builder = await createBuilder();

// Add your resources here, for example:
// const redis = builder.addRedis("cache");
// const postgres = builder.addPostgres("db");

const app = builder.build();
await app.run();

Add integrations

To add Aspire hosting integrations to your polyglot AppHost, use the aspire add command. The following example adds Redis and Azure Storage integrations.

Add the Redis and Azure Storage integrations:
Add integrations
```
aspire add redis
aspire add azure-storage
```
When you add an integration, the Aspire CLI updates .aspire/settings.json with the package reference, regenerates the TypeScript SDK in the .modules directory, and makes the new APIs available in your AppHost code.

Update apphost.ts to use the integrations:

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

const builder = await createBuilder();

// Add a Redis cache
const cache = builder.addRedis('cache');

// Add Azure Storage running as a local emulator
const storage = builder.addAzureStorage('storage').runAsEmulator();

const app = builder.build();
await app.run();

Run the AppHost:
Run AppHost
```
aspire run
```
The Aspire CLI starts the .NET AppHost server, pulls the required container images for Redis and the Azure Storage emulator, and opens the Aspire Dashboard.

Explore all available integrations or see the aspire add reference.

Add a JavaScript application

You can add JavaScript or Node.js applications to your AppHost and have them participate in Aspire’s orchestration, including service discovery and resource references.

Add the JavaScript hosting integration:
Add JavaScript integration
```
aspire add javascript
```

Update apphost.ts to reference your JavaScript application:

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

const builder = await createBuilder();

// Add a Redis cache
const cache = builder.addRedis('cache');

// Add Azure Storage running as a local emulator
const storage = builder.addAzureStorage('storage').runAsEmulator();

// Add a Node.js application
const api = builder
  .addNodeApp('api', '../api', 'server.js')
  .withHttpEndpoint({ port: 3000, env: 'PORT' })
  .withReference(cache);

const app = builder.build();
await app.run();

In this example, the Node.js application at ../api/server.js is registered as a resource named api. It receives a connection string for the Redis cache through service discovery.

See the JavaScript integration for more configuration options.

Troubleshooting

If you encounter issues with your polyglot AppHost, this section provides guidance on diagnosing and resolving common problems.

Common issues

Here are solutions to common problems you may encounter when working with polyglot AppHosts.

”Command not found” errors

Ensure Node.js is installed and available in your PATH:

node --version
npm --version

“Polyglot support not enabled”

Enable polyglot support in the Aspire CLI configuration:

aspire config set features:polyglotSupportEnabled true --global

SDK compilation errors

If you encounter compilation errors in the generated SDK:

Ensure you have the latest version of the Aspire CLI installed
Delete the .modules directory and run aspire run again to regenerate the SDK
Check the Aspire GitHub issues for known problems

Debug mode

Run with debug output to diagnose issues:

aspire run --debug

See the aspire run command reference.

Check logs

Aspire CLI logs are stored at:

Bash
PowerShell

$HOME/.aspire/cli/logs/

$HOME\.aspire\cli\logs\

Feedback

Polyglot AppHost support is a preview feature. Your feedback helps us improve language support and prioritize new features. Please share your experiences, suggestions, and bug reports on the Aspire GitHub repository.

When reporting issues, please include:

The Aspire CLI version (aspire --version)
The Node.js version (node --version)
Steps to reproduce the issue
Any error messages or logs