# Node.js hosting extensions

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

<ThemeImage
  light={nodejsLightIcon}
  dark={nodejsIcon}
  alt="Node.js logo"
  width={100}
  height={100}
  zoomable={false}
  classOverride="float-inline-left icon"
/>

:::note
TypeScript AppHost support for this integration is not yet available. The examples on this page show C# AppHost code only. The `withVite`, `withYarnPackageInstaller`, `withPnpmPackageInstaller`, and `withNpmPackageInstaller` APIs are absent from the generated `.aspire/modules/aspire.mjs` module.
:::

The Aspire Community Toolkit Node.js hosting extensions package provides extra functionality to the [Aspire.Hosting.JavaScript](https://www.nuget.org/packages/Aspire.Hosting.JavaScript) hosting package.

:::caution[Package rename]
In Aspire 13.0, `Aspire.Hosting.NodeJs` was renamed to
[`Aspire.Hosting.JavaScript`](/integrations/frameworks/javascript/).

Use `Aspire.Hosting.JavaScript` for Aspire 13+ applications.
`Aspire.Hosting.NodeJs` is the old package name.
:::

This package provides the following features:

- Running [Vite](https://vitejs.dev/) applications
- Running Node.js applications using [Yarn](https://yarnpkg.com/) and [pnpm](https://pnpm.io/)
- Ensuring that packages are installed before running the application (using the specified package manager)

## Hosting integration

To get started with the Aspire Community Toolkit Node.js hosting extensions, install the [📦 CommunityToolkit.Aspire.Hosting.NodeJS.Extensions](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.NodeJS.Extensions) NuGet package in the app host project.

<InstallPackage packageName="CommunityToolkit.Aspire.Hosting.NodeJS.Extensions" />

## Run specific package managers

This integration extension adds support for running Node.js applications using Yarn or pnpm as the package manager.

### Yarn

To add a Node.js application using Yarn, use the `AddYarnApp` extension method:

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

var yarnApp = builder.AddYarnApp("yarn-demo")
    .WithExternalHttpEndpoints();

builder.AddProject<Projects.ExampleProject>("example")
    .WithReference(yarnApp);

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

### pnpm

To add a Node.js application using pnpm, use the `AddPnpmApp` extension method:

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

var pnpmApp = builder.AddPnpmApp("pnpm-demo")
    .WithExternalHttpEndpoints();

builder.AddProject<Projects.ExampleProject>("example")
    .WithReference(pnpmApp);

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

## Run Vite apps

This integration extension adds support for running the development server for Vite applications. By default, it uses the `npm` package manager to launch, but this can be overridden with the `packageManager` argument.

### Using npm (default)

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

var viteApp = builder.AddViteApp("vite-demo")
    .WithExternalHttpEndpoints();

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

### Using Yarn

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

var viteApp = builder.AddViteApp("yarn-demo", packageManager: "yarn")
    .WithExternalHttpEndpoints();

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

### Using pnpm

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

var viteApp = builder.AddViteApp("pnpm-demo", packageManager: "pnpm")
    .WithExternalHttpEndpoints();

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

## Install packages

When using the `WithNpmPackageInstallation`, `WithYarnPackageInstallation`, or `WithPnpmPackageInstallation` methods, the package manager is used to install the packages before starting the application. These methods are useful to ensure that packages are installed before the application starts, similar to how a C# application would restore NuGet packages before running.

### npm

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

var nodeApp = builder.AddNodeApp("node-demo", "server.js")
    .WithNpmPackageInstallation();

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

### Yarn

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

var yarnApp = builder.AddYarnApp("yarn-demo")
    .WithYarnPackageInstallation();

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

### pnpm

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

var pnpmApp = builder.AddPnpmApp("pnpm-demo")
    .WithPnpmPackageInstallation();

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

## See also

- [Node.js integration](/integrations/frameworks/javascript/)
- [Vite documentation](https://vitejs.dev/)
- [Yarn documentation](https://yarnpkg.com/)
- [pnpm documentation](https://pnpm.io/)
- [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)
- [Aspire integrations overview](/integrations/overview/)
- [Aspire GitHub repo](https://github.com/microsoft/aspire)