Refactor NodeJs Integration #12530

eerhardt · 2025-10-30T22:30:38Z

Description

Refactor JavaScript Integration

Obsolete AddNpmApp.
Add JavaScriptAppResource and AddJavaScriptApp extension method
Refactor AddViteApp to be a specialization of AddJavaScriptApp
Replace NodeInstallerResource with JavaScriptInstallerResource
Add JavaScriptPackageManagerAnnotation to handle different package managers
Replace JavaScriptRunCommandAnnotation with JavaScriptRunScriptAnnotation
Replace JavaScriptBuildCommandAnnotation with JavaScriptBuildScriptAnnotation
Adds WithContainerFilesSource extension method for configuring container file paths

Contributes to #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 - [New article]: Document NodeJs integration changes in Aspire 13 docs-aspire#5443

- Obsolete AddNpmApp. - Add JavaScriptAppResource and AddJavaScriptApp extension method - Refactor AddViteApp to be a specialization of AddJavaScriptApp - Replace NodeInstallerResource with JavaScriptInstallerResource - Add JavaScriptPackageManagerAnnotation to handle different package managers - Replace JavaScriptRunCommandAnnotation with JavaScriptRunScriptAnnotation - Replace JavaScriptBuildCommandAnnotation with JavaScriptBuildScriptAnnotation Contributes to dotnet#8350

github-actions · 2025-10-30T22:30:47Z

🚀 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 -- 12530

Or

Run remotely in PowerShell:

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

Copilot

Pull Request Overview

This PR refactors Node.js application hosting in Aspire by renaming core types and introducing a new AddJavaScriptApp method as the primary API for JavaScript applications. The refactoring establishes a cleaner type hierarchy with JavaScriptAppResource as the base class for both Node.js and Vite applications.

Key Changes:

Introduces AddJavaScriptApp as the main entry point for JavaScript apps, with AddNpmApp now obsoleted
Renames resource types from NodeAppResource/NodeInstallerResource to JavaScriptAppResource/JavaScriptInstallerResource
Refactors package manager annotations from storing executable commands to storing script configurations
Updates default install commands to use npm ci in publish mode instead of npm install
Adds WithContainerFilesSource extension method for configuring container file paths

Reviewed Changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/Aspire.Hosting.NodeJs/JavaScriptAppResource.cs	New base resource class for JavaScript applications with service discovery and container files support
src/Aspire.Hosting.NodeJs/NodeAppResource.cs	Updated to inherit from JavaScriptAppResource instead of ExecutableResource
src/Aspire.Hosting.NodeJs/ViteAppResource.cs	Updated to inherit from JavaScriptAppResource, removed IResourceWithContainerFiles (now on base)
src/Aspire.Hosting.NodeJs/NodeExtensions.cs	Major refactoring: added AddJavaScriptApp, obsoleted AddNpmApp, refactored package manager configuration
src/Aspire.Hosting.NodeJs/JavaScriptPackageManagerAnnotation.cs	New annotation to track package manager executable and script command
src/Aspire.Hosting.NodeJs/JavaScriptRunScriptAnnotation.cs	New annotation for run scripts (replaces JavaScriptRunCommandAnnotation)
src/Aspire.Hosting.NodeJs/JavaScriptBuildScriptAnnotation.cs	New annotation for build scripts (replaces JavaScriptBuildCommandAnnotation)
src/Aspire.Hosting.NodeJs/JavaScriptInstallCommandAnnotation.cs	Simplified to only store args (command now in JavaScriptPackageManagerAnnotation)
src/Aspire.Hosting.NodeJs/JavaScriptInstallerResource.cs	Renamed from NodeInstallerResource
src/Aspire.Hosting/ResourceBuilderExtensions.cs	Added WithContainerFilesSource extension method
tests/*	Comprehensive test updates to use new API and verify new behavior
playground/*	Updated sample applications to use new AddJavaScriptApp API
templates/*	Removed explicit WithNpm(install: true) call (now default behavior)

src/Aspire.Hosting.NodeJs/JavaScriptRunScriptAnnotation.cs

src/Aspire.Hosting.NodeJs/NodeExtensions.cs

playground/AspireWithJavaScript/AspireJavaScript.AppHost/AppHost.cs

tests/Aspire.Hosting.NodeJs.Tests/PackageInstallationTests.cs

…ven if it is called a second time.

eerhardt · 2025-10-31T01:25:42Z

src/Aspire.Hosting/ExecutableResourceBuilderExtensions.cs

        {
+            // Arguments to the executable often contain physical paths that are not valid in the container
+            // Clear them out so that the container can be set up with the correct arguments
+            existingBuilder.WithArgs(c => c.Args.Clear());


@davidfowl - this test was failing before this change -

aspire/tests/Aspire.Hosting.Tests/PublishAsDockerfileTests.cs

Lines 148 to 207 in 2717f1b

public async Task PublishAsDockerFileConfigureContainer()

{

var builder = TestDistributedApplicationBuilder.Create(DistributedApplicationOperation.Publish);

using var tempDir = CreateDirectoryWithDockerFile();

var path = tempDir.Path;

var secret = builder.AddParameter("secret", secret: true);

var frontend = builder.AddNpmApp("frontend", path, "watch")

.WithArgs("/usr/foo")

.PublishAsDockerFile(c =>

{

c.WithBuildSecret("buildSecret", secret);

c.WithArgs("/app");

c.WithVolume("vol", "/app/node_modules");

});

// There should be an equivalent container resource with the same name

// as the npm app resource.

var containerResource = Assert.Single(builder.Resources.OfType<ContainerResource>());

Assert.Equal("frontend", containerResource.Name);

var manifest = await ManifestUtils.GetManifest(frontend.Resource, manifestDirectory: path).DefaultTimeout();

var expected =

$$"""

{

"type": "container.v1",

"build": {

"context": ".",

"dockerfile": "Dockerfile",

"secrets": {

"buildSecret": {

"type": "env",

"value": "{secret.value}"

}

}

},

"args": [

"/app"

],

"volumes": [

{

"name": "vol",

"target": "/app/node_modules",

"readOnly": false

}

],

"env": {

"NODE_ENV": "{{builder.Environment.EnvironmentName.ToLowerInvariant()}}"

}

}

""";

var actual = manifest.ToString();

Assert.Equal(expected, actual, ignoreLineEndingDifferences: true, ignoreWhiteSpaceDifferences: true);

}

The issue is that AddJavaScriptApp calls PublishAsDockerFile, then the test calls WithArgs and then PublishAsDockerFile again. The args in the WithArgs call wasn't getting cleared.

Clarified npm install command requirement for clean install.

davidfowl · 2025-10-31T08:21:21Z

@eerhardt We should default to npm run dev not npm run start

eerhardt · 2025-10-31T11:17:32Z

@eerhardt We should default to npm run dev not npm run start

Done in #12538

eerhardt · 2025-10-31T11:17:39Z

/backport to release/13.0

github-actions · 2025-10-31T11:17:47Z

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

eerhardt added 2 commits October 30, 2025 16:41

Default install command args in publish mode.

615c10b

eerhardt requested review from DamianEdwards, danegsta and davidfowl October 30, 2025 22:30

eerhardt requested a review from mitchdenny as a code owner October 30, 2025 22:30

Copilot AI review requested due to automatic review settings October 30, 2025 22:30

eerhardt mentioned this pull request Oct 30, 2025

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

Open

eerhardt requested review from IEvangelist and aaronpowell October 30, 2025 22:34

Copilot AI reviewed Oct 30, 2025

View reviewed changes

eerhardt added 4 commits October 30, 2025 17:52

Only use clean installs when the lock file exists in publish mode.

a724921

Address copilot feedback

c5a2ea4

More PR feedback

427d88e

Fix PublishAsDockerFile to always clear the args when it is called, e…

176ca5f

…ven if it is called a second time.

eerhardt commented Oct 31, 2025

View reviewed changes

eerhardt mentioned this pull request Oct 31, 2025

Refactor AddNodeApp #12538

Merged

7 tasks

Update npm install command comment in AppHost.cs

de7e5e0

Clarified npm install command requirement for clean install.

davidfowl approved these changes Oct 31, 2025

View reviewed changes

davidfowl merged commit ad6efe8 into dotnet:main Oct 31, 2025
296 checks passed

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

eerhardt mentioned this pull request Oct 31, 2025

Remove NPM install from frontend configuration #12542

Closed

5 tasks

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

[release/13.0] Refactor NodeJs Integration #12559

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Refactor NodeJs Integration #12530

Refactor NodeJs Integration #12530

Uh oh!

eerhardt commented Oct 30, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 30, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eerhardt Oct 31, 2025

Uh oh!

davidfowl commented Oct 31, 2025

Uh oh!

Uh oh!

eerhardt commented Oct 31, 2025 •

edited

Loading

Uh oh!

eerhardt commented Oct 31, 2025

Uh oh!

github-actions bot commented Oct 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	public async Task PublishAsDockerFileConfigureContainer()
	{
	var builder = TestDistributedApplicationBuilder.Create(DistributedApplicationOperation.Publish);

	using var tempDir = CreateDirectoryWithDockerFile();

	var path = tempDir.Path;

	var secret = builder.AddParameter("secret", secret: true);

	var frontend = builder.AddNpmApp("frontend", path, "watch")
	.WithArgs("/usr/foo")
	.PublishAsDockerFile(c =>
	{
	c.WithBuildSecret("buildSecret", secret);
	c.WithArgs("/app");
	c.WithVolume("vol", "/app/node_modules");
	});

	// There should be an equivalent container resource with the same name
	// as the npm app resource.
	var containerResource = Assert.Single(builder.Resources.OfType<ContainerResource>());
	Assert.Equal("frontend", containerResource.Name);

	var manifest = await ManifestUtils.GetManifest(frontend.Resource, manifestDirectory: path).DefaultTimeout();

	var expected =
	$$"""
	{
	"type": "container.v1",
	"build": {
	"context": ".",
	"dockerfile": "Dockerfile",
	"secrets": {
	"buildSecret": {
	"type": "env",
	"value": "{secret.value}"
	}
	}
	},
	"args": [
	"/app"
	],
	"volumes": [
	{
	"name": "vol",
	"target": "/app/node_modules",
	"readOnly": false
	}
	],
	"env": {
	"NODE_ENV": "{{builder.Environment.EnvironmentName.ToLowerInvariant()}}"
	}
	}
	""";

	var actual = manifest.ToString();

	Assert.Equal(expected, actual, ignoreLineEndingDifferences: true, ignoreWhiteSpaceDifferences: true);
	}

Refactor NodeJs Integration #12530

Refactor NodeJs Integration #12530

Uh oh!

Conversation

eerhardt commented Oct 30, 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 30, 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

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eerhardt Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

davidfowl commented Oct 31, 2025

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

eerhardt commented Oct 31, 2025

Uh oh!

github-actions bot commented Oct 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

eerhardt commented Oct 30, 2025 •

edited

Loading

github-actions bot commented Oct 30, 2025 •

edited

Loading

eerhardt commented Oct 31, 2025 •

edited

Loading