Bun integration

⭐ Community Toolkit

The Aspire Bun hosting integration enables you to run Bun applications alongside your Aspire projects in the Aspire app host. Bun is a fast JavaScript runtime and toolkit.

Hosting integration

To get started with the Aspire Bun hosting integration, install the CommunityToolkit.Aspire.Hosting.Bun NuGet package in the app host project.

Install the NuGet package

dotnet add package CommunityToolkit.Aspire.Hosting.Bun

Add Bun app

To add a Bun application to your app host, use the AddBunApp extension method:

var builder = DistributedApplication.CreateBuilder(args);
  
var bunApp = builder.AddBunApp(
    name: "bun-api",
    workingDirectory: "../bun-app")
    .WithHttpEndpoint(port: 3000, env: "PORT");
  
builder.AddProject<Projects.ExampleProject>()
       .WithReference(bunApp);
  
// After adding all resources, run the app...

The AddBunApp method requires:

name: The name of the resource in the Aspire dashboard
workingDirectory: The path to the directory containing your Bun application

By default, the integration looks for an index.ts file as the entrypoint.

Package installation

To ensure packages are installed before running your Bun application, use the WithBunPackageInstaller method:

var builder = DistributedApplication.CreateBuilder(args);
  
var bunApp = builder.AddBunApp("bun-api", "../bun-app")
    .WithBunPackageInstaller()
    .WithHttpEndpoint(port: 3000, env: "PORT");
  
// After adding all resources, run the app...

This runs bun install before starting your application.

Custom entrypoint

To specify a custom entrypoint file, pass it as an additional parameter:

var builder = DistributedApplication.CreateBuilder(args);
  
var bunApp = builder.AddBunApp("bun-api", "../bun-app", "server.ts")
    .WithHttpEndpoint(port: 3000, env: "PORT");
  
// After adding all resources, run the app...

Configure endpoints

Bun applications typically use environment variables to configure the port they listen on. Use WithHttpEndpoint to configure the port and set the PORT environment variable:

var builder = DistributedApplication.CreateBuilder(args);
  
var bunApp = builder.AddBunApp("bun-api", "../bun-app")
    .WithHttpEndpoint(port: 3000, env: "PORT");
  
// After adding all resources, run the app...

Your Bun application can read the PORT environment variable:

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

Working directory

The workingDirectory parameter specifies where the Bun application is located. The Aspire app host will run bun run in this directory to start your Bun application.