Skip to content

Graduate Next.js hosting and JavaScript publishing APIs to stable - #22164

Merged
Maddy Montaquila (maddymontaquila) merged 3 commits into
release/17.0from
maddymontaquila/stabilize-javascript-publishing
Nov 15, 2026
Merged

Maddy Montaquila (maddymontaquila) merged 3 commits into
release/17.0from
maddymontaquila/stabilize-javascript-publishing

Conversation

@maddymontaquila

@maddymontaquila Maddy Montaquila (maddymontaquila) commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Graduate Next.js hosting and the existing JavaScript publishing APIs from ASPIREJAVASCRIPT001, so consumers no longer need experimental-warning suppressions for these scenarios. Retain all APIs, signatures, generated artifacts, runtime behavior, and the existing release/17.0 build-validation behavior.

  • Remove the markers from AddNextJsApp, NextJsAppResource, DisableBuildValidation, both PublishAsStaticWebsite overloads and their internal adapter/core, PublishAsStaticWebsiteOptions, PublishAsNodeServer, and PublishAsPackageScript.
  • Remove now-unnecessary suppressions from existing consumer tests and playgrounds. Those tests now compile and exercise the APIs without suppressing this diagnostic.
  • Document the stable publishing shapes and existing Next.js prerequisites in the integration README. Generated api/*.cs baselines remain untouched.
  • This PR does not graduate Deno or future APIs that might reuse ASPIREJAVASCRIPT001. Deno was independently graduated on the release target; the merge preserves that change.

Fixes # (issue)

User-facing usage

Existing calls remain unchanged; C# callers can remove their ASPIREJAVASCRIPT001 suppressions:

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

builder.AddViteApp("static-site", "../static-site")
    .PublishAsStaticWebsite();

The existing exported TypeScript API names remain unchanged:

await builder.addNextJsApp("frontend", "../frontend");

await builder.addViteApp("static-site", "../static-site")
    .publishAsStaticWebsite();

Publishing contract evaluation

This PR proposes graduation of the current contracts, not a new framework-wide support guarantee or a claim of prior maintainer approval:

Shape Contract retained
Static website Build the configured output directory (dist by default), copy it to YARP's static-file root, and preserve optional API proxying, prefix stripping, and endpoint selection. Unmatched-path behavior is unchanged.
Node server Copy the selected built output and run the specified entry point directly with Node.js.
Package script Run the selected script with the configured package manager and its runtime dependencies; preserve the distinct Node/Bun/Deno image-generation paths.
Next.js Preserve standalone output: public/, .next/standalone/, and .next/static/, with node server.js in the runtime image. A public/ directory remains required.

Next.js configuration inspection remains a static heuristic, not execution of next.config.*. DisableBuildValidation() still supports dynamically supplied configuration without changing the required output. Existing user Dockerfiles and explicit entrypoint overrides retain their current treatment.

Release-specific boundary: release/17.0 has the older resource-annotation validation pipeline, not main's container AddPublishValidation integration. This PR does not port that integration or its Azure graph tests, and does not claim release verification of validation-before-image-build behavior across Azure Container Apps/App Service or excluded-resource handling. The README omits those main-specific guarantees. Validation behavior on the release branch is unchanged by this PR.

The workspace proposal #16839 and SPA-fallback proposal #21871 are not duplicate graduation PRs and are not included here. In particular, this PR does not approve their new APIs or change the current static-site fallback default. Any later change to these now-stable contracts still needs its own compatibility review.

Release branch repair

Replayed only the original stabilization commit c1b09a678919c92a682ce7bf48dd8d299bf0abd0, using its verified original-main fork point 793dfe6e254fe050af24cb7bcfba214066dcaab8, onto release/17.0 at 9a97ab889bfb731de74ead0280be279ffdd000bf. No release-to-head history range was cherry-picked.

The sole conflict was a suppression removal in JavaScriptPublishValidationTests.cs, a test file absent from release. Kept it absent instead of importing main features/tests. A second documentation-only commit removes unsupported release validation guarantees. The replay initially contained 2 scoped commits and 11 files, rather than unrelated main history.

On November 15, merged the release target at a509f094e0ee87d17dc0e1cc9bca84f7ca2623da to resolve reported conflicts. Kept both the Next.js/publishing documentation and the target's independently graduated Deno documentation; removed both obsolete suppressions from the conflicted Deno test file. The target-relative diff remains 11 scoped files. No history rewrite or additional API/runtime behavior changes.

Introduction attribution

David Fowler (@davidfowl) introduced the Next.js resource, validation opt-out, static-website options/helpers, Node-server helper, and original package-script helper in #15736 (introducing commit). The package-script helper was subsequently renamed from PublishAsNpmScript to PublishAsPackageScript in #17382 (rename commit), also by David Fowler (@davidfowl). Attribution was checked against introducing code history and the GitHub commit/PR author identities, not the merge committer or latest editor. No attribution uncertainty identified; these are mentions, not reviewer assignments.

Validation

Current release/17.0-based branch:

  • Passed again after the November 15 conflict resolution, 338 tests, 0 failed, 0 skipped, including the project build, with the exact focused command below. Passed: git diff --cached --check origin/release/17.0 before committing the merge. The earlier CI Final Results failure was an aggregate dependent-job failure also reported on the target by the native PR finisher; it is not worked around in this PR.
  • Passed, 338 tests, 0 failed, 0 skipped: existing consumer/API tests, generated artifact snapshots, and release's existing Next.js validation cases. The negative pipeline test also emitted expected failures from building its deliberately invalid npm fixture; the test run exited 0.
    dotnet test --project tests/Aspire.Hosting.JavaScript.Tests/Aspire.Hosting.JavaScript.Tests.csproj --no-launch-profile -- --filter-class '*.AddJavaScriptAppTests' --filter-class '*.AddViteAppTests' --filter-class '*.NodeJsPublicApiTests' --filter-class '*.AddNodeAppTests' --filter-class '*.AddDenoAppTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'
  • Passed: git diff --check origin/release/17.0...HEAD. No generated snapshot or API baseline changes.
  • Not run on release: main-only JavaScriptPublishValidationTests (absent), successful live framework image builds, CLI multi-framework deployment E2E, live Azure deployment, or a full repository suite. The passing release tests do not establish end-to-end deployment success for every framework or main's stronger validation-graph guarantees.

Historical main-based validation only; not release validation:

  • Passed, 114 baseline tests before changes:
    dotnet test --project tests/Aspire.Hosting.JavaScript.Tests/Aspire.Hosting.JavaScript.Tests.csproj --no-launch-profile -- --filter-class '*.AddJavaScriptAppTests' --filter-class '*.AddViteAppTests' --filter-class '*.NodeJsPublicApiTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'
  • Passed, 344 tests after changes on main:
    dotnet test --project tests/Aspire.Hosting.JavaScript.Tests/Aspire.Hosting.JavaScript.Tests.csproj --no-launch-profile -- --filter-class '*.AddJavaScriptAppTests' --filter-class '*.AddViteAppTests' --filter-class '*.NodeJsPublicApiTests' --filter-class '*.AddNodeAppTests' --filter-class '*.AddDenoAppTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'
  • Passed, 2 Azure validation-graph tests on main:
    dotnet test --project tests/Aspire.Hosting.Azure.Tests/Aspire.Hosting.Azure.Tests.csproj --no-launch-profile -- --filter-class '*.JavaScriptPublishValidationTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'

Checklist

  • Is this feature complete?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No
  • Did you add public API?
    • Yes
      • If yes, did you have an API Review for it?
        • Yes
        • No
      • Did you add <remarks /> and <code /> elements on your triple slash comments?
        • Yes
        • No
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes
      • If yes, have you done a threat model and had a security review?
        • Yes
        • No
    • No

@github-actions

Copy link
Copy Markdown
Contributor

🚀 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/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 22164

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 22164"

@github-actions github-actions Bot added the area-integrations Issues pertaining to Aspire Integrations packages label Nov 11, 2026
@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot November 11, 2026 19:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the changes stabilizing Next.js hosting and JavaScript publishing APIs.

No open issues 🎉

What changed in this PR

Graduates Next.js hosting and existing JavaScript publishing APIs in Aspire.Hosting.JavaScript to stable, preserving signatures, runtime behavior, and build validation. Deno-specific APIs remain experimental; workspace support and SPA fallback remain outside this PR.

Changes:

  • Removes ASPIREJAVASCRIPT001 experimental markers from Next.js resources and publishing APIs.
  • Removes corresponding warning suppressions from existing tests and playground consumers.
  • Documents stable publishing options and Next.js standalone-output prerequisites.
File Description
tests/​Aspire.Hosting.JavaScript.Tests/​NodeJsPublicApiTests.cs Removes the JavaScript experimental-warning suppression.
tests/​Aspire.Hosting.JavaScript.Tests/​AddViteAppTests.cs Exercises existing Vite publishing tests without the suppression.
tests/​Aspire.Hosting.JavaScript.Tests/​AddNodeAppTests.cs Removes the scoped JavaScript warning suppression.
tests/​Aspire.Hosting.JavaScript.Tests/​AddJavaScriptAppTests.cs Exercises existing JavaScript tests without the suppression.
tests/​Aspire.Hosting.JavaScript.Tests/​AddDenoAppTests.cs Removes the JavaScript suppression while retaining Deno’s.
tests/​Aspire.Hosting.Azure.Tests/​JavaScriptPublishValidationTests.cs Removes the suppression from deployment-validation tests.
src/​Aspire.Hosting.JavaScript/​README.md Documents publishing shapes and Next.js prerequisites.
src/​Aspire.Hosting.JavaScript/​PublishAsStaticWebsiteOptions.cs Makes static-website publishing options stable.
src/​Aspire.Hosting.JavaScript/​NextJsAppResource.cs Makes the Next.js resource stable.
src/​Aspire.Hosting.JavaScript/​JavaScriptHostingExtensions.cs Removes experimental markers from publishing, Next.js, and validation opt-out methods.
playground/​AspireWithNode/​AspireWithNode.AppHost/​AppHost.cs Removes suppressions around package-script publishing.
playground/​AspireWithJavaScript/​AspireJavaScript.AppHost/​AppHost.cs Removes suppressions around static-website publishing.

Review effort: Balanced

@github-actions

This comment has been minimized.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Maddy Montaquila and others added 2 commits November 11, 2026 14:23
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The review reports no active issues with stabilizing Next.js hosting and the existing JavaScript publishing APIs.

No open issues 🎉

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Preserve the release branch's Deno graduation alongside stable Next.js and publishing APIs.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@maddymontaquila

Copy link
Copy Markdown
Collaborator Author

Reviewed the dogfood instructions, test-selector report, retry notifications, and both approval-recommended review summaries handed back by the PR finisher. They are informational and request no code changes. The original API scope and attribution remain intact.

Resolved the release-target conflicts in 95b0e0d by preserving both publishing and Deno documentation and removing obsolete suppressions. The focused JavaScript project built and passed all 338 tests. The target-relative diff remains 11 files. The earlier Final Results failure only aggregates dependent-job failures; the native finisher also reports it on the target, so no unrelated workaround was added. New CI will validate the conflict-resolution commit.

🤖 AI-authored reply via Agency Finish PR.

@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

10 / 101 PR test projects · 4 PR jobs, from 10 changed files.

Selected PR test projects (10 / 101)

Aspire.Cli.EndToEnd.Tests, Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Dotnet.Tests, Aspire.Hosting.JavaScript.Tests, Aspire.Hosting.Radius.Tests, Aspire.Hosting.Tests, Aspire.Playground.Tests

Selected PR jobs (4)

cli-starter-validation, extension-e2e, polyglot, typescript-api-compat


How these were chosen — grouped by what changed

⚠️ 9 of the 10 selected test projects come from a single change — src/Aspire.Hosting.JavaScript/JavaScriptHostingExtensions.cs.

🔧 src/Aspire.Hosting.JavaScript/JavaScriptHostingExtensions.cs (changed source)
→ 1 directly: Aspire.Hosting.JavaScript.Tests
→ 8 via the project graph: Aspire.Hosting.Azure.Kubernetes.Tests (2 hops), Aspire.Hosting.Azure.Tests, Aspire.Hosting.Blazor.Tests (2 hops), Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Dotnet.Tests (2 hops), Aspire.Hosting.Radius.Tests (2 hops), Aspire.Hosting.Tests, Aspire.Playground.Tests

📦 affected project Aspire.Hosting.JavaScript
→ 1 test: Aspire.Cli.EndToEnd.Tests

📄 playground/AspireWithJavaScript/AspireJavaScript.AppHost/AppHost.cs (changed)
→ 1 directly: Aspire.Playground.Tests

📄 playground/AspireWithNode/AspireWithNode.AppHost/AppHost.cs (changed)
→ 1 directly: Aspire.Playground.Tests

🔧 src/Aspire.Hosting.JavaScript/NextJsAppResource.cs (changed source)
→ 1 directly: Aspire.Hosting.JavaScript.Tests

🔧 src/Aspire.Hosting.JavaScript/PublishAsStaticWebsiteOptions.cs (changed source)
→ 1 directly: Aspire.Hosting.JavaScript.Tests

🧪 tests/Aspire.Hosting.JavaScript.Tests/AddDenoAppTests.cs (changed test)
→ 1 directly: Aspire.Hosting.JavaScript.Tests

🧪 tests/Aspire.Hosting.JavaScript.Tests/AddJavaScriptAppTests.cs (changed test)
→ 1 directly: Aspire.Hosting.JavaScript.Tests

🧪 tests/Aspire.Hosting.JavaScript.Tests/AddNodeAppTests.cs (changed test)
→ 1 directly: Aspire.Hosting.JavaScript.Tests

🧪 tests/Aspire.Hosting.JavaScript.Tests/AddViteAppTests.cs (changed test)
→ 1 directly: Aspire.Hosting.JavaScript.Tests

🧪 tests/Aspire.Hosting.JavaScript.Tests/NodeJsPublicApiTests.cs (changed test)
→ 1 directly: Aspire.Hosting.JavaScript.Tests

Job reasons

Job Triggered by
cli-starter-validation affected project Aspire.Hosting.JavaScript
extension-e2e • src/Aspire.Hosting.JavaScript/JavaScriptHostingExtensions.cs, src/Aspire.Hosting.JavaScript/NextJsAppResource.cs, src/Aspire.Hosting.JavaScript/PublishAsStaticWebsiteOptions.cs
• affected project Aspire.Hosting.JavaScript
polyglot affected project Aspire.Hosting.JavaScript
typescript-api-compat affected project Aspire.Hosting.JavaScript

Selection computed for commit 95b0e0d.

@maddymontaquila

Copy link
Copy Markdown
Collaborator Author

Reviewed the selector report for 95b0e0d: JavaScript hosting and its downstream projects/jobs are selected. This is informational and requests no code change; the focused release validation remains 338 passing tests, with CI gates left intact.

🤖 AI-authored reply via Agency Finish PR.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the stabilization of Next.js hosting and JavaScript publishing APIs.

No open issues 🎉

Review effort: Balanced

@maddymontaquila

Copy link
Copy Markdown
Collaborator Author

The latest review summary reports no open issues. No further code changes are needed for that review; required CI and approval gates remain enforced before merge.

🤖 AI-authored reply via Agency Finish PR.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@maddymontaquila

Copy link
Copy Markdown
Collaborator Author

The automation has already started attempt 2 for the failed CI jobs. This notice requests no code change; I will leave the existing rerun and required gates intact rather than launch duplicate retries or change unrelated code.

🤖 AI-authored reply via Agency Finish PR.

@maddymontaquila
Maddy Montaquila (maddymontaquila) merged commit 7143d83 into release/17.0 Nov 15, 2026
475 of 480 checks passed
@microsoft-github-policy-service microsoft-github-policy-service Bot added this to the 17.0 milestone Nov 15, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Pull request created: #2169

Generated by PR Documentation Check · copilot · auto · 23.2 AIC · ⌖ 1.07 AIC · ⊞ 7.4K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

📝 Documentation has been drafted in microsoft/aspire.dev#2169 targeting release/17.0.

Removed the experimental callouts and #pragma warning disable ASPIREJAVASCRIPT001 from the JavaScript integration and deployment pages. Marked the ASPIREJAVASCRIPT001 diagnostic page as no longer reported for these APIs. Triggered signals: integration_readme_changed (Aspire.Hosting.JavaScript README), pr_body_has_user_facing_section (User-facing usage), pr_body_has_deprecation_marker, pr_body_has_cli_flag_mention.

Note

This draft PR needs human review before merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-integrations Issues pertaining to Aspire Integrations packages

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants