README.md

November 8, 2021 · View on GitHub

:warning: With .NET 5 & .NET 6, it is recommended to use the scoped CSS feature instead of this library.

Excubo.Blazor.LazyStyleSheet

A major issue on websites is slow page load. In part, this is due to enormous payloads that need to be downloaded in full before a page can be rendered correctly. Minimization and compression help to some degree, but it ignores the awkward fact that many style sheets are only used to a tiny fraction.

With HTTP/2, loading small files rather than one large one is less of a performance concern than with HTTP/1.1. Since Blazor uses HTTP/2 by default, we can make use of this and split style sheets into smaller chunks. Those chunks can then be loaded lazily, i.e. only when a component actually needs it.

Excubo.Blazor.LazyStyleSheet enables you to write dedicated style sheet for each component.

Breaking changes

Version 3.X.Y

Good news! Adding lazy-loaded style sheets to your component just became a whole lot easier. Simply add <Stylesheet Src="path/to/my/style.css" /> to any component. If you write your styles as a Component.razor.css file, you don't need to do anything. And you can now also remove the <StyleSheets /> component in your App.razor, as well as the dependency injection code in your Startup.cs.

Version 2.X.Y

Excubo.Blazor.LazyStyleSheet now contains build tasks to automatically inject the IStyleSheetService when you write your component style as a Component.razor.css or Component.razor.scss file. That means, if you previously manually inserted IStyleSheetService into your component, you now have to remove that.

How to use

1. Install the nuget package Excubo.Blazor.LazyStyleSheet

Excubo.Blazor.LazyStyleSheet is distributed via nuget.org.

Package Manager:

Install-Package Excubo.Blazor.LazyStyleSheet

.NET Cli:

dotnet add package Excubo.Blazor.LazyStyleSheet

Package Reference

<PackageReference Include="Excubo.Blazor.LazyStyleSheet" />

2a. Write your style sheets and put them next to your component

MyComponent.razor:

@page "/hello"

<div class="mystyle">My styled component</div>

MyComponent.razor.css / MyComponent.razor.scss:

.mystyle {
    color: purple
}

2b. Load any stylesheet in your component

MyComponent.razor:

@page "/hello"

<Stylesheet Src="path/to/my/style.min.css" />
<div class="mystyle">My styled component</div>

Remark

Style sheet urls may be added any number of times, and will only be added to the DOM once (as duplicate <link> tags don't achieve anything). This only applies if the url string matches exactly, i.e. there is a difference between https://localhost/css/style.css and css/style.css.

Tips & tricks

Integration with webcompiler

Excubo.Blazor.LazyStyleSheet integrates seemlessly with Excubo.WebCompiler. If you have webcompiler installed, a build task will take care of scss/sass compilation, minification, and compression. The use of webcompiler is strictly optional, but recommended and active by default.

Configuration options

This library can be configured by adding values to your csproj file:

  <PropertyGroup>
    <LazyStyleSheets_StaticAssetFolder>wwwroot</LazyStyleSheets_StaticAssetFolder>
    <LazyStyleSheets_ComponentStyleFolder>css/components</LazyStyleSheets_ComponentStyleFolder>
    <LazyStyleSheets_UseMinifiedStyleSheets>true</LazyStyleSheets_UseMinifiedStyleSheets>
    <LazyStyleSheets_UseGzippedStyleSheets>false</LazyStyleSheets_UseGzippedStyleSheets>
    <LazyStyleSheets_UseWebCompiler>true</LazyStyleSheets_UseWebCompiler>
    <LazyStyleSheets_AutoInject>true</LazyStyleSheets_AutoInject>
  </PropertyGroup>

StaticAssetFolder

The static asset folder should be set to the name of the folder where all your static assets are. By default, that's wwwroot and does not need to be changed.

ComponentStyleFolder

Excubo.Blazor.LazyStyleSheet puts all *.razor.css and *.razor.scss files into a subfolder of the static asset folder, to separate them from other styles. The default location is css/components, so the full path becomes wwwroot/css/components by default.

UseMinifiedStyleSheets

Excubo.Blazor.LazyStyleSheet uses Excubo.WebCompiler, if installed. It then generates minified, and compressed versions of your style sheet automatically. By default, Excubo.Blazor.LazyStyleSheet then uses the minified version to dynamically and lazily load the style sheet. If you do not have Excubo.WebCompiler installed, and you do not generate minified versions of your style sheets any other way, you need to set UseMinifiedStyleSheets to false

  <PropertyGroup>
    <!-- set these values, if you do not use Excubo.WebCompiler or any other minification and compression pipeline -->
    <LazyStyleSheets_UseMinifiedStyleSheets>false</LazyStyleSheets_UseMinifiedStyleSheets>
    <LazyStyleSheets_UseGzippedStyleSheets>false</LazyStyleSheets_UseGzippedStyleSheets>
    <LazyStyleSheets_UseWebCompiler>false</LazyStyleSheets_UseWebCompiler>
  </PropertyGroup>

UseGzippedStyleSheets

Same as with UseMinifiedStyleSheets, serving compressed version of your style sheets is also supported, but deactivated by default. This is because Kestrel does not handle gzipped style sheets correctly by default.

To enable this, add the following to your Startup.cs file:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    /// ...
    /// ...
    
    app.UseStaticFiles(new StaticFileOptions
    {
        OnPrepareResponse = context =>
        {
            var headers = context.Context.Response.Headers;
            HandleCompressedResourced(context, headers);
        }
    });
    app.UseStaticFiles();

    /// ...
    /// ...
}

private static void HandleCompressedResourced(StaticFileResponseContext context, IHeaderDictionary headers)
{
    if (context.File == null)
    {
        return;
    }
    if ((string)headers["Content-Type"] != "application/x-gzip")
    {
        return;
    }
    headers.Add("Content-Encoding", "gzip");
    if (context.File.Name.EndsWith("js.gz", System.StringComparison.InvariantCultureIgnoreCase))
    {
        headers["Content-Type"] = "application/javascript";
    }
    if (context.File.Name.EndsWith("css.gz", System.StringComparison.InvariantCultureIgnoreCase))
    {
        headers["Content-Type"] = "text/css";
    }
}

Activate use of compressed resources in your csproj file:

  <PropertyGroup>
    <LazyStyleSheets_UseGzippedStyleSheets>true</LazyStyleSheets_UseGzippedStyleSheets>
  </PropertyGroup>

Auto Inject

A convenient way of writing styled components is to put the scss/css file in the same folder as the component and name the style file according to the component, e.g. Component.razor and Component.razor.css. That way the css file gets grouped with the component in Visual Studio (and other IDEs with file nesting capability).

This library goes one step further, by making sure that components developed this way automatically have the style injected. If you want to opt out of this feature, simply set <LazyStyleSheets_AutoInject>false</LazyStyleSheets_AutoInject>.

:warning: If you use a custom namespace for your component (i.e. you have an @namespace SomeNamespace directive in your component), then AutoInject won't work for you. Use a <Stylesheet Src="..." /> instead.

Contribute

If you encounter any issues or have ideas for new features, please raise an issue in this repository.