JavaScript monorepo hosting extensions

⭐ Community Toolkit

The 📦 CommunityToolkit.Aspire.Hosting.JavaScript.Extensions package adds Nx and Turborepo monorepo support to the official 📦 Aspire.Hosting.JavaScript integration. Use the official package for individual Node.js, Vite, Next.js, and Bun apps; use this Community Toolkit package when an app belongs to an Nx or Turborepo workspace.

Start with an existing Nx or Turborepo workspace. Pass the workspace root as workingDirectory, then pass the Nx project name or Turborepo package name to AddApp / addApp. For Turborepo, the optional filter selects the package to run.

The extensions add:

AddNxApp / addNxApp for an Nx workspace.
AddTurborepoApp / addTurborepoApp for a Turborepo workspace.
AddApp / addApp for apps within those workspaces.
WithNpm, WithYarn, WithPnpm, and WithBun to select the workspace package manager.
WithPackageManagerLaunch / withPackageManagerLaunch to launch the workspace through the selected package manager.
WithMappedEndpointPort / withMappedEndpointPort to pass an Aspire endpoint’s allocated port to a JavaScript app.

aspire add communitytoolkit-javascript-extensions

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> communitytoolkit-javascript-extensions (CommunityToolkit.Aspire.Hosting.JavaScript.Extensions)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.JavaScript.Extensions@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.JavaScript.Extensions" Version="*" />

aspire add CommunityToolkit.Aspire.Hosting.JavaScript.Extensions

This command adds the package to aspire.config.json so Aspire can generate its TypeScript bindings.

Add an Nx workspace app

AddNxApp / addNxApp models the workspace. Add each runnable project with AddApp / addApp, then decorate that child app with the official JavaScript resource APIs it needs.

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

var nx = builder.AddNxApp("nx-workspace", "../nx-demo")
    .WithNpm(install: true)
    .WithPackageManagerLaunch();

nx.AddApp("blog")
    .WithHttpEndpoint(env: "PORT")
    .WithMappedEndpointPort();

builder.Build().Run();

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const nx: NxResource
nx = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addNxApp(name: string, options?: {
    workingDirectory?: string;
}): NxResource (+1 overload)
Adds an Nx monorepo workspace to the distributed application builder.
addNxApp('nx-workspace', {
  
workingDirectory?: string | undefined
workingDirectory: '../nx-demo',
});
await 
const nx: NxResource
nx.
NxResource.withNpm(install?: boolean): NxResource (+1 overload)
withNpm(true);
await 
const nx: NxResource
nx.
NxResource.withPackageManagerLaunch(options?: {
    packageManager?: string;
}): NxResource (+1 overload)
Configures the Nx workspace to use the specified JavaScript package manager when starting apps.
withPackageManagerLaunch();

const 
const blog: NxAppResource
blog = await 
const nx: NxResource
nx.
NxResource.addApp(name: string, options?: {
    appName?: string;
}): NxAppResource (+1 overload)
addApp('blog');
await 
const blog: NxAppResource
blog.
ExecutableResource.withHttpEndpoint(options?: {
    port?: number;
    targetPort?: number;
    name?: string;
    env?: string;
    isProxied?: boolean;
} | undefined): NxAppResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ 
env?: string | undefined
env: 'PORT' });
await 
const blog: NxAppResource
blog.
NxAppResource.withMappedEndpointPort(options?: {
    endpointName?: string;
} | undefined): NxAppResource (+1 overload)
Maps the endpoint port for the JavaScript app resource to the appropriate command line argument
withMappedEndpointPort();

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

Add a Turborepo workspace app

Use AddTurborepoApp / addTurborepoApp for a Turborepo workspace. The optional filter selects the workspace package to run.

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

var turbo = builder.AddTurborepoApp("turborepo", "../turborepo-demo")
    .WithPnpm(install: true)
    .WithPackageManagerLaunch();

turbo.AddApp("web", filter: "web")
    .WithHttpEndpoint(env: "PORT")
    .WithMappedEndpointPort();

builder.Build().Run();

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const turbo: TurborepoResource
turbo = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addTurborepoApp(name: string, options?: {
    workingDirectory?: string;
}): TurborepoResource (+1 overload)
Adds a Turborepo monorepo workspace to the distributed application builder.
addTurborepoApp('turborepo', {
  
workingDirectory?: string | undefined
workingDirectory: '../turborepo-demo',
});
await 
const turbo: TurborepoResource
turbo.
TurborepoResource.withPnpm(install?: boolean): TurborepoResource (+1 overload)
withPnpm(true);
await 
const turbo: TurborepoResource
turbo.
TurborepoResource.withPackageManagerLaunch(options?: {
    packageManager?: string;
}): TurborepoResource (+1 overload)
Configures the Turborepo workspace to use the specified JavaScript package manager when starting apps.
withPackageManagerLaunch();

const 
const web: TurborepoAppResource
web = await 
const turbo: TurborepoResource
turbo.
TurborepoResource.addApp(name: string, options?: {
    filter?: string;
}): TurborepoAppResource (+1 overload)
addApp('web', { 
filter?: string | undefined
filter: 'web' });
await 
const web: TurborepoAppResource
web.
ExecutableResource.withHttpEndpoint(options?: {
    port?: number;
    targetPort?: number;
    name?: string;
    env?: string;
    isProxied?: boolean;
} | undefined): TurborepoAppResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ 
env?: string | undefined
env: 'PORT' });
await 
const web: TurborepoAppResource
web.
TurborepoAppResource.withMappedEndpointPort(options?: {
    endpointName?: string;
} | undefined): TurborepoAppResource (+1 overload)
Maps the endpoint port for the JavaScript app resource to the appropriate command line argument
withMappedEndpointPort();

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();