ESBuild.AspNetCore is a build-time TypeScript bundling package for ASP.NET Core projects powered by esbuild (GitHub). It was inspired by AspNetCore.SassCompiler, with the same goal of making asset compilation work as a NuGet-powered MSBuild integration instead of a separate Node-based toolchain step.

This repository is currently 100% AI-generated code. Because of that, no pull request will be accepted without prior approval from the maintainer. If you want to contribute, open an issue first and wait for confirmation before investing time in a PR.

• Reads configuration exclusively from esbuild.json
• Runs esbuild during dotnet build and dotnet publish
• Ships platform-specific esbuild binaries inside the NuGet package
• Adds generated files back into the ASP.NET Core static file/publish pipeline
• Supports Debug/Release defaults and configuration-specific per-bundle overrides

• It does not read appsettings.json
• It does not require changes to Program.cs
• It does not provide watch mode, hot reload integration, or runtime bundling
• It does not require Node.js or a global esbuild installation

Add the package to an ASP.NET Core project:

dotnet add package ESBuild.AspNetCore

Then create an esbuild.json file in the project root.

esbuild.json

{
  "Bundles": [
    {
      "EntryPoint": "Scripts/site.ts",
      "Output": "wwwroot/js/site.js"
    }
  ],
  "Configurations": {
    "Debug": {
      "Defaults": {
        "Minify": false,
        "Sourcemap": true
      }
    },
    "Release": {
      "Defaults": {
        "Minify": true,
        "Sourcemap": false
      }
    }
  }
}

After that, dotnet build will generate wwwroot/js/site.js.

Top-level shape:

{
  "Defaults": {},
  "Bundles": [],
  "Configurations": {}
}

Supported default fields:

• Minify
• Sourcemap
• Target
• Format
• Platform

Built-in package defaults:

• Minify: false
• Sourcemap: true
• Target: "es2020"
• Format: "iife"
• Platform: "browser"

Each bundle supports:

• EntryPoint
• Output
• Outdir
• Optional
• Splitting
• Minify
• Sourcemap
• Target
• Format
• Platform
• External
• Define
• Alias
• Loader
• PublicPath

Rules:

• Each bundle must define EntryPoint
• Each bundle must define exactly one of Output or Outdir
• Splitting requires Outdir
• Splitting requires Format: "esm"
• Optional: true skips the bundle if the entry point file does not exist

Each configuration can contain:

• Defaults
• Bundles

Configurations.<name>.Defaults overrides root defaults for that build configuration.

Configurations.<name>.Bundles applies per-bundle overrides matched by EntryPoint. Override entries must define EntryPoint, and that EntryPoint must match exactly one root bundle.

This allows Debug and Release to output different files:

{
  "Bundles": [
    {
      "EntryPoint": "Scripts/site.ts",
      "Output": "wwwroot/js/site.js"
    }
  ],
  "Configurations": {
    "Debug": {
      "Defaults": {
        "Minify": false,
        "Sourcemap": true
      }
    },
    "Release": {
      "Defaults": {
        "Minify": true,
        "Sourcemap": false
      },
      "Bundles": [
        {
          "EntryPoint": "Scripts/site.ts",
          "Output": "wwwroot/js/site.release.js"
        }
      ]
    }
  }
}

{
  "Bundles": [
    {
      "EntryPoint": "Scripts/site.ts",
      "Outdir": "wwwroot/js",
      "Splitting": true,
      "Format": "esm"
    }
  ]
}

When splitting is enabled, the package tracks emitted chunk files using esbuild metafile output and persists the discovered output set under obj/ESBuild.AspNetCore.

Effective bundle settings are resolved in this order:

1. Package defaults
2. Root Defaults
3. Root bundle values
4. Configuration Defaults
5. Configuration-specific bundle override values

If a configuration-specific bundle override specifies Output, it replaces Outdir. If it specifies Outdir, it replaces Output.

The package currently ships vendored esbuild binaries for:

• Windows x64
• Windows arm64
• Linux x64
• Linux arm64
• macOS x64
• macOS arm64

Typical failure cases:

• missing EntryPoint
• missing both Output and Outdir
• defining both Output and Outdir
• unsupported Format
• unsupported Platform
• Splitting used without Outdir
• Splitting used with a format other than esm
• invalid configuration-specific bundle override matching

Builds fail with explicit error messages for invalid configuration.

esbuild warnings and errors are emitted as structured MSBuild diagnostics. Visual Studio and other MSBuild-based tools can therefore associate them with the originating TypeScript file and display their line, column, severity, and ES#### diagnostic code in the IDE.

For example:

Scripts/site.ts(1,21): warning ES0015: Duplicate key "a" in object literal

Warning codes are assigned by esbuild. Many warning types have a specific code, while generic errors can use ES0000.

esbuild diagnostics originate from an MSBuild task instead of the C# compiler. Consequently, <TreatWarningsAsErrors>true</TreatWarningsAsErrors> by itself does not promote esbuild warnings to errors.

To treat all MSBuild task warnings, including esbuild warnings, as errors:

<PropertyGroup>
  <MSBuildTreatWarningsAsErrors>true</MSBuildTreatWarningsAsErrors>
</PropertyGroup>

To treat selected warning codes as errors:

<PropertyGroup>
  <WarningsAsErrors>$(WarningsAsErrors);ES0015</WarningsAsErrors>
</PropertyGroup>

To suppress selected warning codes:

<PropertyGroup>
  <NoWarn>$(NoWarn);ES0015</NoWarn>
</PropertyGroup>

The explicit MSBuild equivalents for the last two settings are MSBuildWarningsAsErrors and MSBuildWarningsAsMessages. The .NET SDK maps WarningsAsErrors and NoWarn to those MSBuild properties.

.editorconfig entries such as dotnet_diagnostic.ES0015.severity = none do not affect esbuild diagnostics because esbuild is an external build tool, not a Roslyn analyzer.

• This project is intentionally build-time only
• Configuration comes only from esbuild.json
• appsettings.json configuration is ignored
• Generated files are included in normal ASP.NET Core content/publish output

Open an issue before opening a PR. Unapproved pull requests should be assumed likely to be closed without merge, especially while the repository is still stabilizing its AI-generated foundation.