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.

Hosting integration

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

aspire add javascript

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

Select an integration to add:

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

#:package Aspire.Hosting.JavaScript@*

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

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

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

// Official Aspire.Hosting.JavaScript API:
await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addBunApp(name: string, appDirectory: string, scriptPath: string): BunAppResource (+2 overloads)
Adds a Bun application to the application model. Bun should be available on the PATH.
addBunApp('bun-api', '../bun-app', 'server.ts');

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

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();

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:

TypeScript
C#

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();

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();

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:

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const bunApp: BunAppResource
bunApp = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addBunApp(name: string, appDirectory: string, scriptPath: string): BunAppResource (+2 overloads)
Adds a Bun application to the application model. Bun should be available on the PATH.
addBunApp(
  'bun-api',
  '../bun-app',
  'src/http/server.ts'
);
await 
const bunApp: BunAppResource
bunApp.
ExecutableResource.withHttpEndpoint(options?: {
    port?: number;
    targetPort?: number;
    name?: string;
    env?: string;
    isProxied?: boolean;
} | undefined): BunAppResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ 
port?: number | undefined
port: 3000, 
env?: string | undefined
env: 'PORT' });

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

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();

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:

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const bunApp: BunAppResource
bunApp = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addBunApp(name: string, appDirectory: string, scriptPath: string): BunAppResource (+2 overloads)
Adds a Bun application to the application model. Bun should be available on the PATH.
addBunApp('bun-api', '../bun-app', 'server.ts');
await 
const bunApp: BunAppResource
bunApp.
ExecutableResource.withHttpEndpoint(options?: {
    port?: number;
    targetPort?: number;
    name?: string;
    env?: string;
    isProxied?: boolean;
} | undefined): BunAppResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ 
port?: number | undefined
port: 3000, 
env?: string | undefined
env: 'PORT' });

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Your Bun application reads the PORT variable at startup:

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}`);