From dd11e062c62178117bb14f1ba4869b387a1b4978 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Fri, 15 Nov 2024 11:36:00 +1100 Subject: [PATCH 1/6] Added Bun hosting docs Closes #2089 --- docs/community-toolkit/hosting-bun.md | 58 +++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/community-toolkit/hosting-bun.md diff --git a/docs/community-toolkit/hosting-bun.md b/docs/community-toolkit/hosting-bun.md new file mode 100644 index 000000000..27cc16042 --- /dev/null +++ b/docs/community-toolkit/hosting-bun.md @@ -0,0 +1,58 @@ +--- +title: Bun hosting +author: aaronpowell +description: Learn how to use the .NET Aspire Bun hosting integration to host Bun applications. +ms.date: 11/15/2024 +--- + +# .NET Aspire Bun hosting + +[!INCLUDE [includes-hosting](../includes/includes-hosting.md)] + +[!INCLUDE [banner](includes/banner.md)] + +In this article, you learn how to use the .NET Aspire Bun hosting integration to host [Bun](https://bun.sh) applications. + +## Hosting integration + +To get started with the .NET Aspire Bun hosting integration, install the [📦 CommunityToolkit.Aspire.Hosting.Bun](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun) NuGet package in the AppHost project. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package CommunityToolkit.Aspire.Hosting.Bun +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). + +## Example usage + +In the _:::no-loc text="Program.cs":::_ file of your app host project, call the `AddBunApp` method to add a Bun application to the builder. + +```csharp +var api = builder.AddBunApp("api") + .WithHttpEndpoint(env: "PORT"); +``` + +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. + +```csharp +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. + +## See also + +- [.NET Aspire Community Toolkit GitHub repo](https://github.com/CommunityToolkit/Aspire) +- [Sample Bun app](https://github.com/CommunityToolkit/Aspire/tree/main/examples/bun) From a4e666395bb2159f631fdc12014495af0f0284ca Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Fri, 15 Nov 2024 11:45:49 +1100 Subject: [PATCH 2/6] Updating to be structured more like the new doc format --- docs/community-toolkit/hosting-bun.md | 31 +++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/community-toolkit/hosting-bun.md b/docs/community-toolkit/hosting-bun.md index 27cc16042..93bb6fc5a 100644 --- a/docs/community-toolkit/hosting-bun.md +++ b/docs/community-toolkit/hosting-bun.md @@ -1,5 +1,5 @@ --- -title: Bun hosting +title: .NET Aspire Bun hosting integration author: aaronpowell description: Learn how to use the .NET Aspire Bun hosting integration to host Bun applications. ms.date: 11/15/2024 @@ -11,11 +11,13 @@ ms.date: 11/15/2024 [!INCLUDE [banner](includes/banner.md)] -In this article, you learn how to use the .NET Aspire Bun hosting integration to host [Bun](https://bun.sh) applications. +[Bun](https://bun.sh) 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 -To get started with the .NET Aspire Bun hosting integration, install the [📦 CommunityToolkit.Aspire.Hosting.Bun](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun) NuGet package in the AppHost project. +The Bun hosting integration models a Bun application as the type. To access this type and APIs that allow you to add it to your app host project, install the [📦 CommunityToolkit.Aspire.Hosting.Bun](https://nuget.org/packages/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 is available in the system path. ### [.NET CLI](#tab/dotnet-cli) @@ -34,13 +36,20 @@ dotnet add package CommunityToolkit.Aspire.Hosting.Bun For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). -## Example usage +## Add a Bun resource -In the _:::no-loc text="Program.cs":::_ file of your app host project, call the `AddBunApp` method to add a Bun application to the builder. +In your app host projec, call the on the `builder` instance to add a Bun application resource as shown in the following example: ```csharp +var builder = DistributedApplication.CreateBuilder(args); + var api = builder.AddBunApp("api") - .WithHttpEndpoint(env: "PORT"); + .WithHttpEndpoint(env: "PORT"); + +var exampleProject = builder.AddProject() + .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. @@ -52,6 +61,16 @@ var api = builder.AddBunApp("api", "../api-service", "start") 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 method to ensure that package installation is run before the application is started. + +```csharp +var api = builder.AddBunApp("api") + .WithHttpEndpoint(env: "PORT") + .WithBunPackageInstaller(); +``` + ## See also - [.NET Aspire Community Toolkit GitHub repo](https://github.com/CommunityToolkit/Aspire) From 77977ce1bec5646d6d8274db995b80602ada9469 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Fri, 15 Nov 2024 11:46:55 +1100 Subject: [PATCH 3/6] Added to the overview for the community toolkit --- docs/community-toolkit/overview.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/community-toolkit/overview.md b/docs/community-toolkit/overview.md index dd029a34b..1e2994a13 100644 --- a/docs/community-toolkit/overview.md +++ b/docs/community-toolkit/overview.md @@ -24,6 +24,9 @@ The community toolkit is a growing project, publishing a set of NuGet packages. - The [Azure Data API Builder](/azure/data-api-builder/overview) integration enables seamless API creation for your data: - [📄 .NET Aspire Azure Data API Builder integration](https://github.com/CommunityToolkit/Aspire/tree/main/src/CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder). - [📦 CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder). +- The [Bun](https://bun.sh) integration provides support for hosting Bun applications: + - [📄 .NET Aspire Bun hosting integration](hosting-bun.md). + - [📦 CommunityToolkit.Aspire.Hosting.Bun](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun). - The [Golang apps](https://go.dev/) integration provides support for hosting Go applications: - [📄 .NET Aspire Go integration](hosting-golang.md). - [📦 CommunityToolkit.Aspire.Hosting.Golang](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Golang). From 5852e817f9d9d999376de06b8367c9b52d9e655a Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Fri, 15 Nov 2024 11:48:05 +1100 Subject: [PATCH 4/6] Adding to the integrations overview --- docs/fundamentals/integrations-overview.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/fundamentals/integrations-overview.md b/docs/fundamentals/integrations-overview.md index ee945b6a1..efbd46904 100644 --- a/docs/fundamentals/integrations-overview.md +++ b/docs/fundamentals/integrations-overview.md @@ -135,8 +135,9 @@ For more information, see [GitHub: Aspire.Hosting.AWS library](https://github.co | Integration docs and NuGet packages | Description | |--|--| | - **Learn More**: [📄 Azure Static Web Apps emulator](../community-toolkit/hosting-azure-static-web-apps.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Azure.StaticWebApps](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Azure.StaticWebApps)
- **Client**: N/A | A hosting integration for the [Azure Static Web Apps emulator](/azure/static-web-apps/static-web-apps-cli-overview) (Note: this does not support deployment of a project to Azure Static Web Apps). | +| - **Learn More**: [📄 Bun hosting](../community-toolkit/hosting-bun.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Bun](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun)
- **Client**: N/A | A hosting integration for Bun apps. | | - **Learn More**: [📄 Go hosting](../community-toolkit/hosting-golang.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Golang](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Golang)
- **Client**: N/A | A hosting integration for Go apps. | -| **Learn More**: [📄 Java/Spring hosting](../community-toolkit/hosting-java.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Java](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Java)
- **Client**: N/A | A integration for running Java code in .NET Aspire either using the local JDK or using a container. | +| - **Learn More**: [📄 Java/Spring hosting](../community-toolkit/hosting-java.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Java](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Java)
- **Client**: N/A | A integration for running Java code in .NET Aspire either using the local JDK or using a container. | | - **Learn More**: [📄 Node.js hosting extensions](../community-toolkit/hosting-nodejs-extensions.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.NodeJs.Extensions](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.NodeJS.Extensions)
- **Client**: N/A | An integration that contains some additional extensions for running Node.js applications | | - **Learn More**: [📄 Ollama](../community-toolkit/ollama.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Ollama](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Ollama)
- **Client**: [📦 Aspire.CommunitToolkit.OllamaSharp](https://nuget.org/packages/CommunityToolkit.Aspire.OllamaSharp) | An Aspire component leveraging the [Ollama](https://ollama.com) container with support for downloading a model on startup. | | - **Learn More**: [📄 Meilisearch hosting](../community-toolkit/hosting-meilisearch.md)
- **Hosting**: [📦 CommunityToolkit.Aspire.Hosting.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Meilisearch)
- **Client**: [📦 Aspire.CommunitToolkit.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Meilisearch) | An Aspire component leveraging the [Meilisearch](https://meilisearch.com) container. | From 871950736c3822357bbd55835c8532500df84ab4 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Fri, 15 Nov 2024 11:48:40 +1100 Subject: [PATCH 5/6] Adding to TOC --- docs/toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/toc.yml b/docs/toc.yml index ef639b3c3..6d915610c 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -257,6 +257,8 @@ items: href: community-toolkit/overview.md - name: Azure Static Web Apps href: community-toolkit/hosting-azure-static-web-apps.md + - name: Bun apps + href: community-toolkit/hosting-bun.md - name: Go apps href: community-toolkit/hosting-golang.md - name: Java/Spring From 8c465dbf87c9caf438c5cbdae099770e974945dc Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Fri, 15 Nov 2024 11:58:36 +1100 Subject: [PATCH 6/6] Removing xref as we don't have API docs --- docs/community-toolkit/hosting-bun.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/community-toolkit/hosting-bun.md b/docs/community-toolkit/hosting-bun.md index 93bb6fc5a..6ecd23743 100644 --- a/docs/community-toolkit/hosting-bun.md +++ b/docs/community-toolkit/hosting-bun.md @@ -15,7 +15,7 @@ ms.date: 11/15/2024 ## Hosting integration -The Bun hosting integration models a Bun application as the type. To access this type and APIs that allow you to add it to your app host project, install the [📦 CommunityToolkit.Aspire.Hosting.Bun](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun) NuGet package in the app host project. +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](https://nuget.org/packages/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 is available in the system path. @@ -38,7 +38,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ## Add a Bun resource -In your app host projec, call the on the `builder` instance to add a Bun application resource as shown in the following example: +In your app host projec, call the `Aspire.Hosting.BunAppExtensions.AddBunApp` on the `builder` instance to add a Bun application resource as shown in the following example: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -63,7 +63,7 @@ The Bun application can be added as a reference to other resources in the app ho ### Ensuring packages are installed -To ensure that the Bun application has all the dependencies installed as defined in the lockfile, you can use the method to ensure that package installation is run before the application is started. +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. ```csharp var api = builder.AddBunApp("api")