Edit

Share via

.NET Aspire Bun hosting

  • Article

Includes: Hosting integration not Client integration

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 app host 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 app host project, install the 📦 CommunityToolkit.Aspire.Hosting.Bun NuGet package in the app host 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 app host 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 app host 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 app host 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