Skip to content

[docs] Update Bun guidance to first-party Aspire.Hosting.JavaScript #1177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mitch Denny (mitchdenny) merged 4 commits into from
Jun 3, 2026
Merged

[docs] Update Bun guidance to first-party Aspire.Hosting.JavaScript #1177

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9bb29c6
docs: update Bun guidance to first-party support
Jun 2, 2026
0503c4e
docs: trim Bun docs changes
Jun 2, 2026
a6a98b7
docs: narrow Bun docs diff
Jun 2, 2026
5f7ee0e
docs: tighten Bun first-party docs diff
Jun 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 105 additions & 43 deletions src/frontend/src/content/docs/integrations/frameworks/bun-apps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,15 @@
---
title: Bun integration
seoTitle: Bun integration for Aspire AppHost (Community Toolkit)
description: Learn how to use the Aspire Community Toolkit Bun hosting integration to orchestrate Bun applications alongside other resources in the Aspire app host.
title: Set up Bun apps in the AppHost
seoTitle: Set up Bun apps in the Aspire AppHost with JavaScript hosting
description: Learn how to use Aspire.Hosting.JavaScript to run Bun applications directly and configure Bun-backed JavaScript resources in your Aspire AppHost.
---

import { Badge } from '@astrojs/starlight/components';

import { TabItem, Tabs } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import InstallPackage from '@components/InstallPackage.astro';
import LearnMore from '@components/LearnMore.astro';
import bunIcon from '@assets/icons/bun-icon.png';

<Badge text="⭐ Community Toolkit" variant="tip" size="large" />

<Image
src={bunIcon}
alt="Bun logo"
Expand All @@ -21,98 +19,162 @@ import bunIcon from '@assets/icons/bun-icon.png';
data-zoom-off
/>

The Aspire Bun hosting integration enables you to run [Bun](https://bun.sh/) 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.
This article is the reference for Bun support in `Aspire.Hosting.JavaScript`. Use `AddBunApp` / `addBunApp` to run a [Bun](https://bun.sh/) application directly in your [`AppHost`](/get-started/app-host/) project, and use `WithBun` / `withBun` when you want other JavaScript resources to use Bun as their package manager.

:::note
TypeScript AppHost support for this integration is not yet available. The examples on this page use the C# AppHost only.
:::caution[Community Toolkit package superseded]
Before Aspire 13.4, Bun hosting was commonly delivered through [📦 CommunityToolkit.Aspire.Hosting.Bun](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun). For Aspire 13.4 and later, use the official `Aspire.Hosting.JavaScript` package and the APIs on this page for new applications.
:::

:::note[Prerequisites]
Install [Bun](https://bun.sh/docs/installation) and make sure the `bun` command is available on your `PATH`.
:::

## Hosting integration

To access the Bun hosting APIs in your [`AppHost`](/get-started/app-host/) project, install the [📦 CommunityToolkit.Aspire.Hosting.Bun](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun) NuGet package:
To access the Bun hosting APIs in your AppHost, install the [📦 Aspire.Hosting.JavaScript](https://www.nuget.org/packages/Aspire.Hosting.JavaScript) package:

<InstallPackage packageName="CommunityToolkit.Aspire.Hosting.Bun" />
<InstallPackage packageName="Aspire.Hosting.JavaScript" />

### Add Bun app

Add a Bun application to your app host using the `AddBunApp` extension method:
Use `AddBunApp` / `addBunApp` to run a Bun script directly from your AppHost:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var bunApp = builder.AddBunApp("bun-api", "../bun-app")
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:
</TabItem>
<TabItem id='typescript' label='TypeScript'>

```typescript title="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();
```

</TabItem>
</Tabs>

`AddBunApp` / `addBunApp` requires:

- **name**: The name of the resource in the Aspire dashboard.
- **workingDirectory**: The path to the directory containing your Bun application, relative to the AppHost project.
- **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`.

By default, the integration looks for an `index.ts` file as the entrypoint.
If `appDirectory` contains a `package.json` file, Aspire automatically uses Bun as the default package manager for the app. When you publish to a container, Aspire uses `oven/bun:1` for the build and runtime stages by default.

### Specify a custom entrypoint

Pass an explicit entrypoint path to run a different script:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();
```

### Install packages before startup
</TabItem>
<TabItem id='typescript' label='TypeScript'>

Call `WithBunPackageInstallation` to run `bun install` before starting the application:
```typescript title="TypeScript — apphost.mts"
import { createBuilder } from './.aspire/modules/aspire.mjs';

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
const builder = await createBuilder();

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

builder.Build().Run();
await builder.build().run();
```

</TabItem>
</Tabs>

### 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:
Bun applications typically read the port from an environment variable. Use `WithHttpEndpoint` / `withHttpEndpoint` to bind the AppHost endpoint to a named environment variable such as `PORT`:

```typescript title="server.ts"
const port = Number(process.env.PORT || 3000);

const server = Bun.serve({
port,
fetch(request) {
return new Response('Hello from Bun!');
},
});

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

### Use Bun with other JavaScript resources

Call `WithBun` / `withBun` on JavaScript resources such as Vite or Next.js apps when you want Bun to handle package installation and container build defaults:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var bunApp = builder.AddBunApp("bun-api", "../bun-app")
.WithHttpEndpoint(port: 3000, env: "PORT");
var frontend = builder.AddViteApp("frontend", "../frontend")
.WithBun()
.WithExternalHttpEndpoints();

builder.Build().Run();
```

Your Bun application reads the `PORT` variable at startup:
</TabItem>
<TabItem id='typescript' label='TypeScript'>

```typescript title="TypeScript — server.ts"
const server = Bun.serve({
port: process.env.PORT || 3000,
fetch(request) {
return new Response("Hello from Bun!");
},
});
```typescript title="TypeScript — apphost.mts"
import { createBuilder } from './.aspire/modules/aspire.mjs';

console.log(`Server listening on port ${server.port}`);
const builder = await createBuilder();

const frontend = await builder.addViteApp('frontend', '../frontend');
await frontend.withBun();
await frontend.withExternalHttpEndpoints();

await builder.build().run();
```

</TabItem>
</Tabs>

<LearnMore>
For more details on JavaScript resources and Bun package-manager options, see
[Set up JavaScript apps in the
AppHost](/integrations/frameworks/javascript/#use-bun).
</LearnMore>

## See also

- [📦 CommunityToolkit.Aspire.Hosting.Bun](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun)
- [📦 Aspire.Hosting.JavaScript](https://www.nuget.org/packages/Aspire.Hosting.JavaScript)
- [Set up JavaScript apps in the AppHost](/integrations/frameworks/javascript/)
- [Bun documentation](https://bun.sh/docs)
- [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)
- [Aspire integrations overview](/integrations/overview/)
- [Aspire GitHub repo](https://github.com/microsoft/aspire)
Loading
Loading