JavaScriptHostingExtensions Methods

AddBunApp(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<BunAppResource>

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

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

JavaScriptHostingExtensions.cs#L381-L626

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 Bun application.

scriptPath string The path to the script (for example, server.ts) relative to appDirectory to run.

Returns

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

Remarks

This method executes the script directly using bun <script>. Bun natively runs JavaScript and TypeScript files so no transpile step is required. If the application directory contains a package.json file, Bun will be added as the default package manager. When publishing to a container, the default base image is oven/bun:1 for both the build and runtime stages.

Examples

Add a Bun app to the application model:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddBunApp("api", "../api", "server.ts");

builder.Build().Run();

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#L691-L699

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.

AddNextJsApp(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<NextJsAppResource>

Adds a Next.js app to the distributed application builder.

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

JavaScriptHostingExtensions.cs#L1540-L1609

Parameters

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

name string The name of the Next.js app.

appDirectory string The path to the directory containing the Next.js app.

runScriptName string optional The name of the script that runs the Next.js dev server. Defaults to "dev".

Returns

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

Remarks

This method configures the Next.js application for both local development and publishing. In run mode, it starts the Next.js dev server with the correct port binding. In publish mode, it generates a multi-stage Dockerfile using Next.js standalone output mode, which copies public/, .next/standalone/, and .next/static/ into a Node.js runtime container.

The Next.js application must have output: "standalone" configured in next.config.ts and a public/ directory (even if empty) for the published container to build correctly.

The following example creates a Next.js app.

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

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#L123-L286

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();

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#L1362-L1501

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();

DisableBuildValidation(IResourceBuilder<NextJsAppResource>) extension IResourceBuilder<NextJsAppResource>

Disables deploy-time build validation checks for the Next.js application.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<NextJsAppResource> DisableBuildValidation(
        this IResourceBuilder<NextJsAppResource> builder)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L1627

Parameters

builder IResourceBuilder<NextJsAppResource> The resource builder.

Returns

IResourceBuilder<NextJsAppResource> The resource builder for chaining.

Remarks

By default, JavaScriptHostingExtensions.AddNextJsApp adds publish prerequisite steps that verify the Next.js configuration (e.g. that output: "standalone" is set). Use this method to suppress those checks when the configuration is set dynamically or via an external mechanism that cannot be detected by static file inspection.

PublishAsNodeServer(IResourceBuilder<TResource>, string, string) extension IResourceBuilder<TResource>

Configures the JavaScript application to publish as a standalone Node.js server that runs a built artifact directly.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> PublishAsNodeServer<TResource>(
        this IResourceBuilder<TResource> builder,
        string entryPoint,
        string outputPath = ".")
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L908-L935

Parameters

builder IResourceBuilder<TResource> The JavaScript resource builder.

entryPoint string The relative path to the Node.js entry point to execute in the published container after the build completes, such as .output/server/index.mjs or build/index.js.

outputPath string optional The relative path containing the built runtime files to copy into the published container. Defaults to the application root.

Returns

IResourceBuilder<TResource> The updated resource builder.

Remarks

Use this method for frameworks that produce a Node.js server artifact during the build and recommend running that artifact directly in production rather than invoking a package manager script at runtime. The application source is still built using the configured package manager and build script; this method only changes the publish-time runtime container shape.

The container files source path is automatically set to outputPath so that only the built output directory is copied into the runtime container, not the full application source.

PublishAsPackageScript(IResourceBuilder<TResource>, string, string?) extension IResourceBuilder<TResource>

Configures the JavaScript application to publish as a Node.js server that uses a package.json script at runtime.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> PublishAsPackageScript<TResource>(
        this IResourceBuilder<TResource> builder,
        string scriptName = "start",
        string? runScriptArguments = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L973-L998

Parameters

builder IResourceBuilder<TResource> The JavaScript resource builder.

scriptName string optional The name of the package.json script to run in the published container. For example, start invokes the configured package manager's run command for the start script, such as npm run start, pnpm run start, yarn run start, or bun run start.

runScriptArguments string? optional Optional arguments appended after the script name at runtime, such as -- --port "$PORT".

Returns

IResourceBuilder<TResource> The updated resource builder.

Remarks

Use this method for frameworks where the production server depends on packages in node_modules at runtime. The resulting container includes the full application with production dependencies installed.

This method is appropriate for frameworks like Nuxt (where useAsyncData / useFetch requires the full Nitro environment), Remix (where react-router-serve is an npm dependency), and Astro SSR (where the built entry point imports unbundled @astrojs/* packages).

For frameworks that produce a self-contained server artifact that does not require node_modules, use JavaScriptHostingExtensions.PublishAsNodeServer instead for a smaller runtime image.

PublishAsStaticWebsite(IResourceBuilder<TResource>, Action<PublishAsStaticWebsiteOptions>) extension IResourceBuilder<TResource>

Configures the JavaScript application to publish as a standalone static website served by YARP.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> PublishAsStaticWebsite<TResource>(
        this IResourceBuilder<TResource> builder,
        Action<PublishAsStaticWebsiteOptions>? configure = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L722-L724

Parameters

builder IResourceBuilder<TResource> The JavaScript resource builder.

configure Action<PublishAsStaticWebsiteOptions> optional Optional callback to configure PublishAsStaticWebsiteOptions.

Returns

IResourceBuilder<TResource> The updated resource builder.

Remarks

The published container uses a YARP reverse proxy image for static file serving. To add an API reverse-proxy, use the overload that accepts an apiPath and apiTarget.

PublishAsStaticWebsite(IResourceBuilder<TResource>, string, IResourceBuilder<IResourceWithServiceDiscovery>, Action<PublishAsStaticWebsiteOptions>)

extension IResourceBuilder<TResource>

Configures the JavaScript application to publish as a standalone static website served by YARP, with an API reverse-proxy to the specified resource.

public static class JavaScriptHostingExtensions
{
    public static IResourceBuilder<TResource> PublishAsStaticWebsite<TResource>(
        this IResourceBuilder<TResource> builder,
        string apiPath,
        IResourceBuilder<IResourceWithServiceDiscovery> apiTarget,
        Action<PublishAsStaticWebsiteOptions>? configure = null)
    {
        // ...
    }
}

JavaScriptHostingExtensions.cs#L759-L762

Parameters

builder IResourceBuilder<TResource> The JavaScript resource builder.

apiPath string A path prefix to reverse-proxy to a backend API. For example, /api proxies all requests matching /api/{"{**catch-all}"} to the backend resource.

apiTarget IResourceBuilder<IResourceWithServiceDiscovery> The backend resource to proxy API requests to. YARP uses service discovery to resolve the appropriate endpoint, preferring HTTPS when available.

configure Action<PublishAsStaticWebsiteOptions> optional Optional callback to configure PublishAsStaticWebsiteOptions.

Returns

IResourceBuilder<TResource> The updated resource builder.

Remarks

The published container uses a YARP reverse proxy image for static file serving and API reverse-proxy. YARP natively supports HTTPS backends and service discovery, so API proxy requests work correctly across all deployment targets (Docker Compose, Azure App Service, etc.).

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#L2046-L2089

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();

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#L1932

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.

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#L1720-L1764

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. JavaScriptHostingExtensions.PublishAsPackageScript also uses the Bun image for the runtime stage unless a custom runtime image is configured. 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();

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#L1670-L1686

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.

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#L1868-L1909

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.

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#L1951

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.

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#L1650-L1655

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");

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#L1789-L1832

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.