Refactor AddNodeApp #12538

eerhardt · 2025-10-31T02:54:40Z

Description

Obsolete the existing AddNodeApp that takes a file path only
Introduce a new AddNodeApp that takes a directory path and a file path relative to that directory
Includes a default Dockerfile for the Node application
Add Npm package manager support if the directory contains a package.json file

Fix #8350

Checklist

Is this feature complete?
- Yes. Ready to ship.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
Does the change make any security assumptions or guarantees?
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire-docs issue (consider using one of the following templates):
    - [New article]: Document NodeJs integration changes in Aspire 13 docs-aspire#5443
    - [Breaking change]: Aspire.Hosting.NodeJs library breaks docs-aspire#5444

github-actions · 2025-10-31T02:54:53Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 12538

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 12538"

- Obsolete the existing AddNodeApp that takes a file path only - Introduce a new AddNodeApp that takes a directory path and a file path relative to that directory - Includes a default Dockerfile for the Node application - Add Npm package manager support if the directory contains a package.json file

Copilot

Pull Request Overview

This pull request refactors the Node.js application hosting API in Aspire to separate the application directory from the script path, improving clarity and consistency. The PR changes the default run script from "start" to "dev" and adds support for custom run script arguments.

Key Changes:

Introduces a new AddNodeApp overload that takes separate appDirectory and scriptPath parameters, marking the old signature as obsolete
Changes the default run script from "start" to "dev" for AddJavaScriptApp
Adds WithRunScript extension method to support custom script arguments
Automatically configures npm as the package manager when package.json exists

Reviewed Changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Aspire.Hosting.NodeJs/NodeExtensions.cs	Added new `AddNodeApp` overload with improved API design, marked old overload as obsolete, changed default run script to "dev", enhanced `WithRunScript` to support arguments
src/Aspire.Hosting.NodeJs/Aspire.Hosting.NodeJs.csproj	Added OverloadResolutionPriorityAttribute to project for C# overload resolution
tests/Aspire.Hosting.Tests/DistributedApplicationTests.cs	Updated test to use new `AddNodeApp` API signature with separate directory and script parameters
tests/Aspire.Hosting.NodeJs.Tests/PackageInstallationTests.cs	Updated tests to expect "dev" as default script, added test for `WithRunScript` with custom arguments, minor formatting fix
tests/Aspire.Hosting.NodeJs.Tests/NodeJsPublicApiTests.cs	Updated tests to use new `AddNodeApp` API signature
tests/Aspire.Hosting.NodeJs.Tests/NodeAppFixture.cs	Updated fixture to use new `AddNodeApp` API signature
tests/Aspire.Hosting.NodeJs.Tests/AddNodeAppTests.cs	Added comprehensive tests for new API behavior including Dockerfile generation and npm detection
playground/AspireWithJavaScript/AspireJavaScript.NodeApp/*	Added new sample Node.js application with Express server, package.json, and HTML frontend
playground/AspireWithJavaScript/AspireJavaScript.AppHost/AppHost.cs	Updated existing apps to explicitly use "start" script and added new Node.js app with "dev" script

Files not reviewed (1)

playground/AspireWithJavaScript/AspireJavaScript.NodeApp/package-lock.json: Language not supported

Comments suppressed due to low confidence (1)

src/Aspire.Hosting.NodeJs/NodeExtensions.cs:28

Corrected grammar: 'Node should available' should be 'Node should be available'. This appears in the obsoleted method documentation as well.

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

src/Aspire.Hosting.NodeJs/NodeExtensions.cs

IEvangelist

LGTM

Use multi-stage build. Set NODE_ENV. Expose the port. Use a non-root user.

eerhardt · 2025-10-31T16:42:35Z

src/Aspire.Hosting.NodeJs/NodeExtensions.cs

-                            .Copy(".", ".");
+
+                    var builderStage = dockerfileContext.Builder
+                        .From($"node:{nodeVersion}-slim", "build")


@davidfowl @mitchdenny - if we decided to use -alpine by default, the size reduces by about 100MB.

Using the playground app I added, sizes are:

Current: 334 MB

Combining all steps into a single stage: 349 MB

Using node:22-alpine: 237 MB

Should we default to that instead? And if someone needs a different base image, we can add support for defining the base image via an annotation.

I went with -alpine by default. We will allow people to change the base image with an annotation.

eerhardt · 2025-10-31T19:05:51Z

/backport to release/13.0

github-actions · 2025-10-31T19:06:07Z

Started backporting to release/13.0: https://github.com/dotnet/aspire/actions/runs/18982618551

davidfowl · 2025-10-31T19:48:42Z

Tested and it works!

robrich · 2025-10-31T20:21:50Z

This fixes many parts of #8350. But it doesn't fix .WithHttpOtelCollector(). Browser apps need to use HTTP and can't use gRPC for OTEL.

eerhardt mentioned this pull request Oct 31, 2025

Refactor NodeJs Integration #12530

Merged

7 tasks

eerhardt force-pushed the AddNodeAppRefactor branch 2 times, most recently from 76bf405 to e3dc209 Compare October 31, 2025 12:12

eerhardt force-pushed the AddNodeAppRefactor branch from e3dc209 to 294ee9f Compare October 31, 2025 12:21

eerhardt mentioned this pull request Oct 31, 2025

[New article]: Document NodeJs integration changes in Aspire 13 dotnet/docs-aspire#5443

Open

eerhardt added the breaking-change Issue or PR that represents a breaking API or functional change over a prerelease. label Oct 31, 2025

eerhardt marked this pull request as ready for review October 31, 2025 12:31

eerhardt requested a review from mitchdenny as a code owner October 31, 2025 12:31

eerhardt requested review from DamianEdwards, IEvangelist, aaronpowell, Copilot and davidfowl October 31, 2025 12:31

Copilot AI reviewed Oct 31, 2025

View reviewed changes

src/Aspire.Hosting.NodeJs/NodeExtensions.cs Outdated Show resolved Hide resolved

IEvangelist approved these changes Oct 31, 2025

View reviewed changes

eerhardt added 2 commits October 31, 2025 09:58

Minor PR feedback

2cd076d

Optimize the node dockerfile

c541a08

Use multi-stage build. Set NODE_ENV. Expose the port. Use a non-root user.

eerhardt commented Oct 31, 2025

View reviewed changes

Use alpine for the base image of NodeApps for size optimization.

1225fc7

github-actions bot mentioned this pull request Oct 31, 2025

[release/13.0] Refactor AddNodeApp #12569

Merged

eerhardt merged commit cadf510 into dotnet:main Oct 31, 2025
582 of 585 checks passed

eerhardt deleted the AddNodeAppRefactor branch October 31, 2025 19:08

dotnet-policy-service bot added this to the 13.0 milestone Oct 31, 2025

robrich mentioned this pull request Oct 31, 2025

Make Aspire better for client-side JavaScript developers. #8350

Closed

davidfowl mentioned this pull request Nov 8, 2025

Add OTEL HTTP support for JS client apps #12834

Open

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Refactor AddNodeApp #12538

Refactor AddNodeApp #12538

Uh oh!

eerhardt commented Oct 31, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

IEvangelist left a comment

Uh oh!

eerhardt Oct 31, 2025

Uh oh!

eerhardt Oct 31, 2025

Uh oh!

eerhardt commented Oct 31, 2025

Uh oh!

github-actions bot commented Oct 31, 2025

Uh oh!

Uh oh!

davidfowl commented Oct 31, 2025

Uh oh!

robrich commented Oct 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Refactor AddNodeApp #12538

Refactor AddNodeApp #12538

Uh oh!

Conversation

eerhardt commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

github-actions bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes:

Reviewed Changes

Uh oh!

Uh oh!

IEvangelist left a comment

Choose a reason for hiding this comment

Uh oh!

eerhardt Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

eerhardt Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

eerhardt commented Oct 31, 2025

Uh oh!

github-actions bot commented Oct 31, 2025

Uh oh!

Uh oh!

davidfowl commented Oct 31, 2025

Uh oh!

robrich commented Oct 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

eerhardt commented Oct 31, 2025 •

edited

Loading

github-actions bot commented Oct 31, 2025 •

edited

Loading