Customize scoped CSS bundle route path in Blazor Web App

Question

Customize scoped CSS bundle route path in Blazor Web App

iKingNinja 185

I created a Blazor Web App and I want to customize the route where <ProjectName>.styles.css is served. However app.MapStaticAssets() does not provide a way to do so. The docs about CSS isolation say that the bundle is generated at build time so apparently the only way to achieve this is to write a custom MSBuild target for customizing <ProjectName>.staticwebassets.endpoints.json but I don't know how exactly that would be done.

0 comments

Answer accepted by question author

1 additional answer

Your answer

Answer 1

Hi @iKingNinja ,

Thanks for reaching out.

The scoped CSS bundle is generated at build time and its route is wired up through that pipeline, so there isn’t a supported way in MapStaticAssets() to change just the route for <ProjectName>.styles.css. While you may be able to modify the generated staticwebassets.endpoints.json with a custom MSBuild target, I wouldn’t recommend it since that file is treated as build output and can change between SDK versions.

Please also treat the code snippets below as reference examples. You may need to adjust the project name, paths, middleware order, base path, or hosting setup to match your specific project structure.

In normal scenarios, the suitable approach is to avoid hardcoding the URL altogether and let Blazor resolve it for you:

<link rel="stylesheet" href="@Assets["MyApp.styles.css"]" />

This way the framework handles the correct path (including fingerprinting), and you don’t have to worry about where the file is physically served from.

If your goal is to influence where static assets are exposed more broadly, you can set a base path in your project file:

<PropertyGroup>
  <StaticWebAssetBasePath>assets</StaticWebAssetBasePath>
</PropertyGroup>

That shifts the base URL for all static web assets, not just the scoped CSS bundle. You’d still reference the file using @Assets[...], and Blazor will resolve the updated path automatically.

If you’re trying to control the bundle name itself, that comes from the project/package identity. For example:

<PropertyGroup>
  <PackageId>MyCustomName</PackageId>
</PropertyGroup>

which would result in:

<link rel="stylesheet" href="@Assets["MyCustomName.styles.css"]" />

For cases where you specifically need a custom public-facing URL (for example /custom/path/styles.css), the suggested approach is to introduce a rewrite rather than changing how the asset is generated:

app.Use(async (context, next) =>
{
    if (context.Request.Path.Equals("/custom/path/styles.css", StringComparison.OrdinalIgnoreCase))
    {
        context.Request.Path = "/MyApp.styles.css";
    }

    await next();
});

app.MapStaticAssets();

You can then reference /custom/path/styles.css, and the app will internally serve the original bundle. If you’re using a reverse proxy or CDN, doing the rewrite there is often even cleaner.

If you need full control over the file name, location, and route, the supported escape hatch is to opt out of the built-in bundling:

<PropertyGroup>
  <DisableScopedCssBundling>true</DisableScopedCssBundling>
</PropertyGroup>

At that point you’d take over the process yourself (collecting the generated scoped CSS from obj, bundling or copying it into wwwroot, and referencing it however you like). It gives you complete flexibility, but you’re also responsible for maintaining that pipeline.

Hope this helps! If my answer was helpful, I would greatly appreciate it if you could follow the instructions here so others with the same problem can benefit as well.

Answer 2

In a Blazor Web App using MapStaticAssets, the route where the scoped CSS bundle (<ProjectName>.styles.css) is served is determined by the static web assets system and the generated *.staticwebassets.endpoints.json. There’s no supported way to change that route via MapStaticAssets options or by customizing the generated endpoints file.

The supported customization point for scoped CSS is the scope identifier and the base path for static web assets, not the individual bundle route:

To change the base path under which all static web assets (including scoped.styles.css and the app’s styles bundle) are exposed, set StaticWebAssetBasePath in the project file:
```
   <PropertyGroup>
     <StaticWebAssetBasePath>_content/$(PackageId)</StaticWebAssetBasePath>
   </PropertyGroup>
```
This moves scoped.styles.css and the rest of the app’s assets under the specified base path.
In server-side Blazor apps using MapStaticAssets, static assets (including the CSS isolation bundle) are meant to be referenced via the ComponentBase.Assets indexer, which resolves the fingerprinted URL for the asset:
```
   <link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
   <link rel="stylesheet" href="@Assets["app.css"]" />
   <link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />
```
Here, @Assets["BlazorSample.styles.css"] returns the correct, fingerprinted route for the styles bundle. The route itself is controlled by the static web assets system and MapStaticAssets, not by user code.

Because of this design, the recommended and supported approach is:

Keep app.MapStaticAssets(); in Program.cs.
Reference the styles bundle using @Assets["<ProjectName>.styles.css"] in components.
Optionally adjust the global base path for all static assets with StaticWebAssetBasePath.

Writing a custom MSBuild target to modify <ProjectName>.staticwebassets.endpoints.json or to remap only the scoped CSS bundle to a different route is not documented or supported in the provided guidance.

References:

Share via

Customize scoped CSS bundle route path in Blazor Web App

1 additional answer

Your answer