Bun integration

The Aspire Bun hosting integration enables you to run Bun applications alongside your other Aspire resources in the app host. Bun apps participate in the same service discovery, health checks, OpenTelemetry export, and Aspire dashboard support as the rest of your solution.

Community Toolkit package deprecated

The 📦 CommunityToolkit.Aspire.Hosting.Bun package is deprecated. Bun support has graduated to the official Aspire.Hosting.JavaScript package.

Hosting integration

To access the Bun hosting APIs in your AppHost project, install the 📦 Aspire.Hosting.JavaScript NuGet package:

Aspire CLI

Aspire CLI — Add Aspire.Hosting.JavaScript package

aspire add javascript

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Aspire CLI — Example output prompt

Select an integration to add:

> javascript (Aspire.Hosting.JavaScript)
> Other results listed as selectable options...

Note

If there's only one result, the CLI selects it automatically. You'll still need to confirm the version.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.JavaScript@*

PackageReference (*.csproj)

XML — Add Aspire.Hosting.JavaScript package reference

<PackageReference Include="Aspire.Hosting.JavaScript" Version="*" />

Migrate from the Community Toolkit package

Remove CommunityToolkit.Aspire.Hosting.Bun and install Aspire.Hosting.JavaScript. The official API requires the app directory and script path separately:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Deprecated Toolkit API:
// builder.AddBunApp(
//     "bun-api",
//     workingDirectory: "../bun-app",
//     entryPoint: "server.ts");

// Official Aspire.Hosting.JavaScript API:
builder.AddBunApp("bun-api", "../bun-app", "server.ts");

builder.Build().Run();

TypeScript

apphost.mts

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

const builder = await createBuilder();

// Deprecated Toolkit API:
// await builder.addBunApp('bun-api', {
//   workingDirectory: '../bun-app',
//   entryPoint: 'server.ts',
// });

// Official Aspire.Hosting.JavaScript API:
await builder.addBunApp('bun-api', '../bun-app', 'server.ts');

await builder.build().run();

The official package requires both paths. In TypeScript, replace the Toolkit options object with the official appDirectory and scriptPath arguments.

Add Bun app

Add a Bun application to your AppHost using AddBunApp / addBunApp:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var bunApp = builder.AddBunApp("bun-api", "../bun-app", "server.ts")
    .WithHttpEndpoint(port: 3000, env: "PORT");

builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(bunApp);

builder.Build().Run();

TypeScript

apphost.mts

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

const builder = await createBuilder();

const bunApp = await builder.addBunApp('bun-api', '../bun-app', 'server.ts');
await bunApp.withHttpEndpoint({ port: 3000, env: 'PORT' });

await builder.build().run();

AddBunApp requires:

• name: The name of the resource in the Aspire dashboard.
• appDirectory: The path to the directory containing your Bun application, relative to the AppHost project.
• scriptPath: The script to run relative to appDirectory, such as server.ts.

The resource is typed as BunAppResource.

Specify a custom entrypoint

Pass a different scriptPath to run a different script:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var bunApp = builder.AddBunApp("bun-api", "../bun-app", "src/http/server.ts")
    .WithHttpEndpoint(port: 3000, env: "PORT");

builder.Build().Run();

TypeScript

apphost.mts

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

const builder = await createBuilder();

const bunApp = await builder.addBunApp(
  'bun-api',
  '../bun-app',
  'src/http/server.ts'
);
await bunApp.withHttpEndpoint({ port: 3000, env: 'PORT' });

await builder.build().run();

Install packages before startup

When your Bun app includes a package.json file, Aspire uses Bun as the package manager and installs packages automatically before the application starts.

Configure HTTP endpoints

Bun applications typically read the port from an environment variable. Use WithHttpEndpoint to declare the HTTP endpoint and bind it to a named environment variable:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var bunApp = builder.AddBunApp("bun-api", "../bun-app", "server.ts")
    .WithHttpEndpoint(port: 3000, env: "PORT");

builder.Build().Run();

TypeScript

apphost.mts

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

const builder = await createBuilder();

const bunApp = await builder.addBunApp('bun-api', '../bun-app', 'server.ts');
await bunApp.withHttpEndpoint({ port: 3000, env: 'PORT' });

await builder.build().run();

Your Bun application reads the PORT variable at startup:

server.ts

const server = Bun.serve({
  port: process.env.PORT || 3000,
  fetch(request) {
    return new Response('Hello from Bun!');
  },
});

console.log(`Server listening on port ${server.port}`);

See also

• 📦 Aspire.Hosting.JavaScript
• JavaScript hosting integration
• Bun documentation
• Aspire integrations overview
• Aspire GitHub repo