JavaScriptHostingExtensions Methods

Docs / Reference / Search C# APIs / Aspire.Hosting.JavaScript / JavaScriptHostingExtensions / Methods

Methods

Docs Reference Search C# APIs Aspire.Hosting.JavaScript JavaScriptHostingExtensions Methods

Class Methods 11 members

Provides extension methods for adding JavaScript applications to an Hosting.IDistributedApplicationBuilder.

AddJavaScriptApp(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<JavaScriptAppResource>

Adds a JavaScript application resource to the distributed application using the specified app directory and run script.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<JavaScriptAppResource> AddJavaScriptApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string runScriptName = "dev")
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L333-L341

Parameters

builder IDistributedApplicationBuilder The distributed application builder to which the JavaScript application resource will be added.

name string The unique name of the JavaScript application resource. Cannot be null or empty.

appDirectory string The path to the directory containing the JavaScript application.

runScriptName string optional The name of the npm script to run when starting the application. Defaults to "dev". Cannot be null or empty.

Returns

IResourceBuilder<JavaScriptAppResource> A resource builder for the newly added JavaScript application resource.

Remarks

If a Dockerfile does not exist in the application's directory, one will be generated automatically when publishing. The method configures the resource with Node.js defaults and sets up npm integration.

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

AddNodeApp(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<NodeAppResource>

Adds a node application to the application model. Node should be available on the PATH.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<NodeAppResource> AddNodeApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string scriptPath)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L119-L282

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to.

name string The name of the resource.

appDirectory string The path to the directory containing the node application.

scriptPath string The path to the script relative to the app directory to run.

Returns

IResourceBuilder<NodeAppResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This method executes a Node script directly using node script.js. If you want to use a package manager you can add one and configure the install and run scripts using the provided extension methods. If the application directory contains a package.json file, npm will be added as the default package manager.

Examples

Add a Node app to the application model using yarn and 'yarn run dev' for running during development:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddNodeApp("frontend", "../frontend", "app.js")
       .WithYarn()
       .WithRunScript("dev");

builder.Build().Run();

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

AddViteApp(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<ViteAppResource>

Adds a Vite app to the distributed application builder.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<ViteAppResource> AddViteApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string runScriptName = "dev")
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L511-L650

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to.

name string The name of the Vite app.

appDirectory string The path to the directory containing the Vite app.

runScriptName string optional The name of the script that runs the Vite app. Defaults to "dev".

Returns

IResourceBuilder<ViteAppResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

The following example creates a Vite app using npm as the package manager.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddViteApp("frontend", "./frontend");

builder.Build().Run();

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

Experimental — ASPIREEXTENSION001

WithBrowserDebugger(IResourceBuilder<T>, string) extension IResourceBuilder<T>

Configures a browser debugger for the JavaScript application resource, enabling browser-based debugging through a child resource that launches when the parent application is ready.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<T> WithBrowserDebugger<T>(
        this IResourceBuilder<T> builder,
        string browser = "msedge")
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L1037-L1080

Parameters

builder IResourceBuilder<T> The resource builder for the JavaScript application.

browser string optional The browser to use for debugging. Defaults to "msedge". Supported values include "msedge" and "chrome".

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for chaining additional configuration.

Exceptions

InvalidOperationException Thrown when the parent resource does not have an HTTP or HTTPS endpoint, or when the IDE extension does not support browser debugging.

Remarks

This method creates a child JavaScript.BrowserDebuggerResource that waits for the parent JavaScript application to start, then launches a browser debug session targeting the parent's HTTP or HTTPS endpoint. The parent resource must have at least one HTTP or HTTPS endpoint configured.

Examples

Add browser debugging to a JavaScript application:

var builder = DistributedApplication.CreateBuilder(args);
builder.AddViteApp("frontend", "./frontend")
    .WithBrowserDebugger();

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithBuildScript(IResourceBuilder<TResource>, string, string[]?) extension IResourceBuilder<TResource>

Adds a build script annotation to the resource builder using the specified command-line arguments.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> WithBuildScript<TResource>(
        this IResourceBuilder<TResource> resource,
        string scriptName,
        string[]? args = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L924

Parameters

resource IResourceBuilder<TResource> The resource builder to which the build script annotation will be added.

scriptName string The name of the script to be executed when the resource is built.

args string[]? optional An array of command-line arguments to use for the build script.

Returns

IResourceBuilder<TResource> The same resource builder instance with the build script annotation applied.

Remarks

Use this method to specify custom build scripts for JavaScript application resources during deployment.

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithBun(IResourceBuilder<TResource>, bool, string[]?) extension IResourceBuilder<TResource>

Configures the JavaScript resource to use Bun as the package manager and optionally installs packages before the application starts.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> WithBun<TResource>(
        this IResourceBuilder<TResource> resource,
        bool install = true,
        string[]? installArgs = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L736-L776

Parameters

resource IResourceBuilder<TResource> The JavaScript application resource builder.

install bool optional When true (default), automatically installs packages before the application starts. When false, only sets the package manager annotation without creating an installer resource.

installArgs string[]? optional Additional command-line arguments passed to "bun install". When null, defaults are applied based on publish mode and lockfile presence.

Returns

IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

Bun forwards script arguments without requiring the -- command separator, so this method configures the resource to omit it. When publishing and a bun lockfile ( bun.lock or bun.lockb) is present, --frozen-lockfile is used by default. Publishing to a container requires Bun to be present in the build image. This method configures a Bun build image when one is not already specified. To use a specific Bun version, configure a custom build image (for example, oven/bun:<tag>) using ContainerResourceBuilderExtensions.WithDockerfileBaseImage.

Examples

Run a Vite app using Bun as the package manager:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddViteApp("frontend", "./frontend")
       .WithBun()
       .WithDockerfileBaseImage(buildImage: "oven/bun:latest"); // To use a specific Bun image

builder.Build().Run();

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithNpm(IResourceBuilder<TResource>, bool, string?, string[]?) extension IResourceBuilder<TResource>

Configures the Node.js resource to use npm as the package manager and optionally installs packages before the application starts.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> WithNpm<TResource>(
        this IResourceBuilder<TResource> resource,
        bool install = true,
        string? installCommand = null,
        string[]? installArgs = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L692-L705

Parameters

resource IResourceBuilder<TResource> The NodeAppResource.

install bool optional When true (default), automatically installs packages before the application starts. When false, only sets the package manager annotation without creating an installer resource.

installCommand string? optional The install command itself passed to npm to install dependencies.

installArgs string[]? optional The command-line arguments passed to npm to install dependencies.

Returns

IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1.

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithPnpm(IResourceBuilder<TResource>, bool, string[]?) extension IResourceBuilder<TResource>

Configures the Node.js resource to use pnpm as the package manager and optionally installs packages before the application starts.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> WithPnpm<TResource>(
        this IResourceBuilder<TResource> resource,
        bool install = true,
        string[]? installArgs = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L875-L901

Parameters

resource IResourceBuilder<TResource> The NodeAppResource.

install bool optional When true (default), automatically installs packages before the application starts. When false, only sets the package manager annotation without creating an installer resource.

installArgs string[]? optional The command-line arguments passed to "pnpm install".

Returns

IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1.

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithRunScript(IResourceBuilder<TResource>, string, string[]?) extension IResourceBuilder<TResource>

Adds a run script annotation to the specified JavaScript application resource builder, specifying the script to execute and its arguments during run mode.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> WithRunScript<TResource>(
        this IResourceBuilder<TResource> resource,
        string scriptName,
        string[]? args = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L943

Parameters

resource IResourceBuilder<TResource> The resource builder to which the run script annotation will be added.

scriptName string The name of the script to be executed when the resource is run.

args string[]? optional An array of arguments to pass to the script.

Returns

IResourceBuilder<TResource> The same resource builder instance with the run script annotation applied, enabling further configuration.

Remarks

Use this method to specify a custom script and its arguments that should be executed when the resource is executed in RunMode.

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithViteConfig(IResourceBuilder<ViteAppResource>, string) extension IResourceBuilder<ViteAppResource>

Configures the Vite app to use the specified Vite configuration file instead of the default resolution behavior.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<ViteAppResource> WithViteConfig(
        this IResourceBuilder<ViteAppResource> builder,
        string configPath)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L673-L678

Parameters

builder IResourceBuilder<ViteAppResource> The resource builder.

configPath string The path to the Vite configuration file. Relative to the Vite service project root.

Returns

IResourceBuilder<ViteAppResource> The resource builder.

Remarks

Use this method to specify a specific Vite configuration file if you need to override the default Vite configuration resolution behavior.

Examples

Use a custom Vite configuration file:

var builder = DistributedApplication.CreateBuilder(args);
var viteApp = builder.AddViteApp("frontend", "./frontend")
    .WithViteConfig("./vite.production.config.js");

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithYarn(IResourceBuilder<TResource>, bool, string[]?) extension IResourceBuilder<TResource>

Configures the Node.js resource to use yarn as the package manager and optionally installs packages before the application starts.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> WithYarn<TResource>(
        this IResourceBuilder<TResource> resource,
        bool install = true,
        string[]? installArgs = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L800-L840

Parameters

resource IResourceBuilder<TResource> The NodeAppResource.

install bool optional When true (default), automatically installs packages before the application starts. When false, only sets the package manager annotation without creating an installer resource.

installArgs string[]? optional The command-line arguments passed to "yarn install".

Returns

IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1.

ATS export

Available to Polyglot AppHosts through the Aspire Type System.