Guidance on integrating build generated files into Static Web Assets

[maraf]

[EDIT by guardrex to add the metadata]

Related

• WebAssembly SDK - what is the replacement for <WasmExtraFilesToDeploy>? runtime#118146
• WasmBootConfigFileName doesn't work with WasmAppBuilder without additional configuration runtime#117900

Files outside of wwwroot can be linked into wwwroot and thus picked up by SWA

<Content Include="generate\main.js" Link="wwwroot\main.js" CopyToOutputDirectory="PreserveNewest" />

We need to figure out which SWA target is ideal for hooking typescript (or any other custom) build onto.

Alternative approach, use Microsoft.VisualStudio.JavaScript.Sdk, eg https://github.com/microsoft/fluentui-blazor/blob/dev/src/Core.Assets/Microsoft.FluentUI.AspNetCore.Components.Assets.esproj. I'm not sure what's the preferred path.

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: d47f38e2-bc36-cfb8-b0cc-17a534689f8b
• Version Independent ID: 3fec6e08-fc99-7a5c-796f-3f2347cad891
• Platform ID: 5c42c2c8-be1b-60de-8cde-f9b8d8c24f5f
• Content: Static files in ASP.NET Core
• Content Source: aspnetcore/fundamentals/static-files.md
• Service: aspnet-core
• Sub-service: fundamentals
• GitHub Login: @wadepickett
• Microsoft Alias: wpickett

---

Associated WorkItem - 558542

[guardrex]

@maraf ... Is this is a general ASP.NET Core scenario? ... i.e. for ...

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/static-files?view=aspnetcore-9.0

... or is it only for Blazor ... i.e. for ...

https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/static-files?view=aspnetcore-9.0

[maraf]

Good question. I think both? Maybe the approach is in fact common and nothing blazor specific is needed.

[guardrex]

I added the metadata for the main doc set article, which maps to Wade.

[wadepickett]

Thanks @maraf and @guardrex!

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-03-04
Issue: 36249
Model: GitHub Copilot

---

Issue Analysis: Guidance on integrating build-generated files into Static Web Assets

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The issue requests documentation guidance on how to integrate build-generated files (e.g., TypeScript output, bundled JavaScript) into ASP.NET Core's Static Web Assets (SWA) pipeline. Currently, the static files article does not cover how to hook custom build steps (such as TypeScript compilation or other asset generation) into the SWA discovery process so that generated files are served with the full benefits of Map Static Assets (fingerprinting, compression, caching).

The issue identifies two potential approaches:

1. MSBuild <Content> linkage: Using <Content Include="generate\main.js" Link="wwwroot\main.js" CopyToOutputDirectory="PreserveNewest" /> to link generated files into wwwroot so SWA can pick them up.
2. Microsoft.VisualStudio.JavaScript.Sdk: Using .esproj projects (e.g., as demonstrated in the fluentui-blazor repo).

The submitter (@maraf, a Microsoft team member working on the runtime) confirmed this applies to general ASP.NET Core scenarios, not just Blazor-specific ones. Documentation is needed to clarify which SWA target is ideal for hooking custom builds onto, and which approach is preferred.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/fundamentals/static-files.md	19-43	"Map Static Assets" overview (.NET 9+ moniker)
Main article	aspnetcore/fundamentals/static-files.md	390-421	"Large collection of assets" section
RCL TypeScript integration	aspnetcore/razor-pages/ui-class/includes/ui-class6.md	105-128	"Typescript integration" (RCL-specific, .NET 6 moniker)
RCL article (main)	aspnetcore/razor-pages/ui-class.md	121-136	"Typescript integration"
Blazor static files	aspnetcore/blazor/fundamentals/static-files.md	47-75	"Static asset delivery in server-side Blazor apps"

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential documentation Updates

1. New section in the static files article for build-generated assets

File: aspnetcore/fundamentals/static-files.md
Location: After the current "Map Static Assets" overview paragraph (line ~42), within the >= aspnetcore-9.0 moniker range.
Type: New section

Current content (lines 42-43):

Map Static Assets doesn't provide features for minification or other file transformations. Minification is usually handled by custom code or [third-party tooling](xref:blazor/fundamentals/index#community-links-to-blazor-resources).

:::moniker-end

Suggested direction:
A new section titled something like "Integrate build-generated files into Static Web Assets" that covers:

## Integrate build-generated files into Static Web Assets

Files generated during the build process (for example, TypeScript compilation output or bundled JavaScript) aren't automatically discovered by Static Web Assets (SWA) because they don't exist in `wwwroot` at design time. To include build-generated files in the SWA pipeline so they benefit from fingerprinting, compression, and caching, use one of the following approaches.

### Link generated files into wwwroot

Use the MSBuild `<Content>` item with a `Link` attribute to map generated files into `wwwroot`. For example, if a build step produces `generate/main.js`, link it into the web root:

```xml
<Content Include="generate\main.js" Link="wwwroot\main.js" 
    CopyToOutputDirectory="PreserveNewest" />

The linked file is treated as though it resides in wwwroot and is picked up by SWA during the build.

Hook into the SWA build target

To ensure custom build steps run before SWA discovers assets, add the build target as a dependency of the appropriate SWA target. For TypeScript compilation using Microsoft.TypeScript.MSBuild, add the following to a <PropertyGroup> in the project file:

For .NET 7 or later:

<ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
  CompileTypeScript;
  $(ResolveCurrentProjectStaticWebAssetsInputsDependsOn)
</ResolveCurrentProjectStaticWebAssetsInputsDependsOn>

For .NET 6:

<PrepareForBuildDependsOn>
  CompileTypeScript;
  GetTypeScriptOutputForPublishing;$(PrepareForBuildDependsOn)
</PrepareForBuildDependsOn>

Use the JavaScript Project SDK

For projects with complex JavaScript/TypeScript build pipelines, consider using Microsoft.VisualStudio.JavaScript.Sdk (.esproj). This SDK integrates npm-based builds into the .NET project system.

For more information, see JavaScript Project SDK.

#### 2. Cross-reference from existing TypeScript integration guidance (RCL article)

**File:** [`aspnetcore/razor-pages/ui-class/includes/ui-class6.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/razor-pages/ui-class/includes/ui-class6.md#L105-L128)
**Location:** Lines 105-128 ("Typescript integration" section)
**Type:** Cross-reference addition

The existing RCL TypeScript integration guidance only covers the RCL scenario. A cross-reference to the new section in the static files article would help developers who arrive at the RCL docs but need the general ASP.NET Core pattern.

**Suggested direction:**
Add a note after the existing TypeScript integration section:

```markdown
> [!NOTE]
> For guidance on integrating build-generated files into Static Web Assets in non-RCL ASP.NET Core projects, see <xref:fundamentals/static-files#integrate-build-generated-files-into-static-web-assets>.

🎯 Suggested Action Plan

For documentation team review

1. Investigate preferred SWA target: Engage with @maraf or the ASP.NET Core engineering team to confirm:

   • Which MSBuild target is the recommended hook point for custom build steps in .NET 9+ (likely ResolveCurrentProjectStaticWebAssetsInputsDependsOn).
   • Whether Microsoft.VisualStudio.JavaScript.Sdk is the preferred approach for complex JS/TS build pipelines.
   • Whether the <Content ... Link="wwwroot\..." /> approach is fully supported and recommended.

2. Add new section to static files article: aspnetcore/fundamentals/static-files.md

   • Navigate to: Line 42
   • Section: After "Map Static Assets" overview, within >= aspnetcore-9.0 moniker
   • Consider: New section with MSBuild examples and build target hooking guidance

3. Add cross-reference from RCL TypeScript integration: aspnetcore/razor-pages/ui-class/includes/ui-class6.md

   • Navigate to: Line 128
   • Section: "Typescript integration"
   • Consider: [!NOTE] block linking to the new general-purpose guidance

4. Consider Blazor cross-reference: Optionally add a cross-reference in aspnetcore/blazor/fundamentals/static-files.md since Blazor apps also benefit from this pattern.

⚠️ Review Considerations

• Verify which MSBuild targets are recommended for .NET 9+ vs. earlier versions (the RCL docs currently show different targets for .NET 6 vs. .NET 7+).
• Confirm with engineering whether <Content Include="..." Link="wwwroot\..." /> fully participates in SWA fingerprinting and compression, or if only the DependsOn target approach works.
• Check if Microsoft.VisualStudio.JavaScript.Sdk documentation exists on Microsoft Learn and can be linked.
• The related runtime issues (dotnet/runtime#118146 and dotnet/runtime#117900) are both closed/completed, which may provide additional clarity on the resolved patterns.
• The existing TypeScript integration guidance in the RCL article applies only to Razor Class Libraries — the static files article currently has no guidance for general ASP.NET Core project build integration with SWA.

🔗 References

• Published article: Static files in ASP.NET Core
• Published article: Razor Class Library - TypeScript integration
• Published article: Blazor static files
• Related issue: dotnet/runtime#118146 - WebAssembly SDK replacement for WasmExtraFilesToDeploy (closed)
• Related issue: dotnet/runtime#117900 - WasmBootConfigFileName (closed)
• External example: fluentui-blazor .esproj