AspNet.AssetManager 4.4.1

AspNet.AssetManager

Use Vite or Webpack with ASP.NET Core MVC and Razor Pages. AspNet.AssetManager reads your bundler's manifest and renders the correct <script> and <link> tags: from the dev server (with hot reload) in development, and from hashed static files in production.

<link-bundle fallback="Layout" />
<script-bundle defer fallback="Layout" />

Features

• Tag helpers: <link-bundle />, <script-bundle /> and <style-bundle />.
• Per-view bundles by convention: the bundle name is inferred from the view being rendered, e.g. Views/Home/Index.cshtml → Views_Home_Index.
• Fallbacks: if a view has no bundle of its own, a shared one (e.g. Layout) is used.
• Vite and Webpack: supports Vite manifests and key/value manifests such as webpack-assets-manifest.
• Same markup in every environment: assets come from the dev server in development and from wwwroot in production.
• Full Vite CSS: <link-bundle /> collects stylesheets from imported shared chunks, in the same order Vite applies them.
• Targets .NET 8, 9 and 10.

Getting started

The quickest way to start is a project template from AspNet.Frontend.Templates. It sets up the .NET side and the bundler config for you:

dotnet new install AspNet.Frontend.Templates
dotnet new mvcvite   # also: mvcvitets, mvcwebpack(ts), razorvite(ts), razorwebpack(ts)

To add AspNet.AssetManager to an existing project, follow the steps below.

1. Install

dotnet add package AspNet.AssetManager

2. Register services

Program.cs:

using AspNet.AssetManager;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddAssetManager(builder.Configuration, builder.Environment);

var app = builder.Build();

app.UseStaticFiles();
// ...

3. Import the tag helpers

Views/_ViewImports.cshtml:

@addTagHelper *, AspNet.AssetManager

4. Render bundles in your layout

Views/Shared/_Layout.cshtml:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>@ViewData["Title"]</title>
  <link-bundle fallback="Layout" />
</head>
<body>
  @RenderBody()
  <script-bundle defer fallback="Layout" />
  @await RenderSectionAsync("Scripts", required: false)
</body>
</html>

Each page now loads its own bundle (Views_Home_Index, Views_Account_Login, ...) if one exists, and the Layout bundle if not.

5. Configure your bundler

Vite

appsettings.json:

{
  "AssetManager": {
    "PublicDevServer": "http://localhost:5173",
    "ManifestType": "Vite"
  }
}

vite.config.js. aspnet-buildtools finds the entry points for your views and serves a manifest from the Vite dev server:

import { viteConfig } from 'aspnet-buildtools';
import { defineConfig } from 'vite';

export default defineConfig({
  ...viteConfig,
  build: {
    ...viteConfig.build,
    assetsDir: '',
    manifest: 'assets-manifest.json', // must match AssetManager:ManifestFile
    outDir: 'wwwroot/dist',           // must match wwwroot + AssetManager:PublicPath
  },
  server: {
    cors: true,
  },
});

For hot module replacement, add the Vite client to your layout in development:

<environment include="Development">
  <script src="http://localhost:5173/@@vite/client" type="module"></script>
</environment>

Webpack

appsettings.json:

{
  "AssetManager": {
    "PublicDevServer": "http://localhost:9000"
  }
}

webpack.config.js, using webpack-assets-manifest and aspnet-buildtools:

import path from 'node:path';
import { webpackConfig } from 'aspnet-buildtools';
import { WebpackAssetsManifest } from 'webpack-assets-manifest';

export default {
  ...webpackConfig,
  output: {
    path: path.resolve(import.meta.dirname, 'wwwroot/dist'),
    filename: '[name]-[contenthash].js',
    publicPath: '/dist/',
  },
  plugins: [new WebpackAssetsManifest()],
  devServer: {
    headers: { 'Access-Control-Allow-Origin': '*' },
    port: 9000,
  },
};

Tag helpers

• name: bundle to render. If omitted, it is resolved as described in Bundle names.
• fallback: bundle to render if name cannot be found in the manifest.
• module: adds type="module". Defaults to true for Vite manifests and false otherwise.

Nothing is rendered if neither bundle exists, so it is safe to put these tags in a shared layout.

Bundle names

The bundle for a tag helper is chosen in this order:

1. The name attribute, e.g. <script-bundle name="Checkout" />.
2. ViewData["Bundle"], set in a view or controller. A value starting with / is converted the same way as view paths: "/Some/Bundle" → Some_Bundle.
3. The path of the view being rendered:

If that bundle is not in the manifest, the fallback bundle is used.

aspnet-buildtools produces these names: a Views/Home/Index.cshtml.js (or .ts) next to a view becomes the Views_Home_Index entry, and any *.bundle.js file becomes a named bundle (Layout.bundle.js → Layout).

Configuration

All settings live in the AssetManager section of appsettings.json:

Development vs. production

The app counts as being in development when IWebHostEnvironment.IsDevelopment() returns true.

If the dev server is not running, a DevServerException ("Development server not started!") is thrown.

Rendering from code

For full control, inject IAssetService:

@using AspNet.AssetManager
@inject IAssetService AssetService

@{
    var bundle = ViewData.GetBundleName() ?? Html.GetBundleName();
}

@* Tags *@
@await AssetService.GetScriptTagAsync(bundle, "Layout", ScriptLoad.Defer)
@await AssetService.GetLinkTagAsync(bundle, "Layout")
@await AssetService.GetStyleTagAsync("Critical")

@* Paths *@
@AssetService.WebPath
@await AssetService.GetBundlePathAsync("SomeBundle.js")
@await AssetService.GetBundlePathAsync("SomeBundle", FileType.CSS)

ScriptLoad can be Normal, Async, Defer or AsyncDefer.

Related projects

• AspNet.Frontend.Templates: dotnet new templates and example projects for Vite and Webpack.
• aspnet-buildtools: npm package that generates bundler entry points and aliases from your Razor views.

Building from source

The build uses NUKE:

./build.sh Test        # Windows: .\build.cmd Test

src/AspNet.AssetManager.Demo is a small Webpack-based MVC app for trying changes locally (npm install && npm start, then dotnet run).

License

MIT