From fea38f8cf33afe1b067a1d6f4aa28d25f93c11fc Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
<268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Thu, 30 Apr 2026 17:45:45 +0000
Subject: [PATCH] docs: document build-only container validation and
DisableBuildOnlyContainerValidation API
Documents the new publish/deploy validation that requires build-only
containers (AddViteApp, AddJavaScriptApp) to be consumed by another resource
via PublishWithContainerFiles or PublishWithStaticFiles.
Adds a new section explaining the validation error users may see, and documents
the DisableBuildOnlyContainerValidation() escape hatch API for scenarios where
the validation is too restrictive.
Also adds a new bullet to the Common mistakes section to highlight this
publish-time check.
Relates to microsoft/aspire#16582
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../docs/deployment/javascript-apps.mdx | 38 +++++++++++++++++++
1 file changed, 38 insertions(+)
diff --git a/src/frontend/src/content/docs/deployment/javascript-apps.mdx b/src/frontend/src/content/docs/deployment/javascript-apps.mdx
index 6a099acd9..854fc76fc 100644
--- a/src/frontend/src/content/docs/deployment/javascript-apps.mdx
+++ b/src/frontend/src/content/docs/deployment/javascript-apps.mdx
@@ -622,6 +622,43 @@ The same production decision applies to `AddJavaScriptApp`:
The difference is that `AddJavaScriptApp` does not assume a particular development server. You choose the run script and the build script, but production still depends on deciding which deployed resource owns the final HTTP surface.
+## Build-only container validation
+
+When you publish or deploy an Aspire app, Aspire validates that every build-only container resource (such as one added with `AddViteApp` or `AddJavaScriptApp`) is consumed by another resource via `PublishWithContainerFiles` or `PublishWithStaticFiles`. If Aspire finds an unconsumed build-only container, it stops the pipeline with an error similar to:
+
+```
+Resource 'frontend' is a build-only container that is not consumed by any other resource.
+Wire it through PublishWithContainerFiles or PublishWithStaticFiles, or call
+builder.Pipeline.DisableBuildOnlyContainerValidation() to suppress this check.
+```
+
+This validation catches the common mistake of adding a Vite or JavaScript app and forgetting to connect it to a resource that serves the built files in production.
+
+### Disable the validation
+
+If you have a scenario where the validation is too restrictive — for example, the container is consumed by infrastructure that Aspire cannot inspect — you can disable the check for the whole app by calling `DisableBuildOnlyContainerValidation` on the pipeline:
+
+```csharp
+#pragma warning disable ASPIREPIPELINES001
+using Aspire.Hosting.Pipelines;
+
+var builder = DistributedApplication.CreateBuilder(args);
+
+// ...add resources...
+
+builder.Pipeline.DisableBuildOnlyContainerValidation();
+
+await builder.Build().RunAsync();
+```
+
+
+
+The `DisableBuildOnlyContainerValidation` method is part of the `Aspire.Hosting.Pipelines` namespace and is currently marked experimental (`ASPIREPIPELINES001`). Suppress the diagnostic or set `ASPIREPIPELINES001` in your project file when using it.
+
## Common mistakes
- Expecting `AddViteApp` to be the deployed production web server.
@@ -630,6 +667,7 @@ The difference is that `AddJavaScriptApp` does not assume a particular developme
- Using `.WithEnvironment(...)` on `AddViteApp` to pass the API URL to the deployed SPA.
- Calling `.WithHttpEndpoint()` on `AddViteApp`.
- Using `VITE_*` variables for values that must be resolved at runtime in an already-built SPA.
+- Adding a Vite or JavaScript app without calling `PublishWithContainerFiles` or `PublishWithStaticFiles`, which causes a publish-time validation error.
For runtime configuration guidance, see [JavaScript