Edit

Share via

.NET Aspire Bun hosting

Includes: Hosting integration included Hosting integration only — Client integration not included Client integration not included

Note

This integration is part of the .NET Aspire Community Toolkit and isn't officially supported by the .NET Aspire team.

Bun is a modern, fast, and lightweight framework for building web applications with TypeScript. The .NET Aspire Bun hosting integration allows you to host Bun applications in your .NET Aspire AppHost project, and provide it to other resources in your application.

Hosting integration

The Bun hosting integration models a Bun application as the Aspire.Hosting.ApplicationModel.BunAppResource type. To access this type and APIs that allow you to add it to your AppHost project, install the 📦 CommunityToolkit.Aspire.Hosting.Bun NuGet package in the AppHost project.

This integration expects that the Bun executable has already been installed on the host machine, and that it's available in the system path.

dotnet add package CommunityToolkit.Aspire.Hosting.Bun

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add a Bun resource

In your AppHost project, call the Aspire.Hosting.BunAppExtensions.AddBunApp on the builder instance to add a Bun application resource as shown in the following example:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddBunApp("api")
                 .WithHttpEndpoint(env: "PORT");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(api);

// After adding all resources, run the app...

By default the working directory of the application will be a sibling folder to the AppHost matching the name provided to the resource, and the entrypoint will be :::no-loc text="index.ts"::. Both of these can be customized by passing additional parameters to the AddBunApp method.

var api = builder.AddBunApp("api", "../api-service", "start")
    .WithHttpEndpoint(env: "PORT");

The Bun application can be added as a reference to other resources in the AppHost project.

Ensuring packages are installed

To ensure that the Bun application has all the dependencies installed as defined in the lockfile, you can use the Aspire.Hosting.BunAppExtensions.WithBunPackageInstaller method to ensure that package installation is run before the application is started.

var api = builder.AddBunApp("api")
                 .WithHttpEndpoint(env: "PORT")
                 .WithBunPackageInstaller();

See also