Blazor #2 - How to work with SASS in Blazor

CSS isolation in Blazor was introduced as a way to encapsulate component styles, preventing them from leaking into other components or the global scope. While this feature has its advantages, it might not align with everyone’s development style, especially if you’re used to the flexibility and power of SASS.

In this post, I’ll explain why I’m not a fan of CSS isolation in Blazor, and I’ll walk you through how to implement SASS using the AspNetCore.SassCompiler NuGet package instead of relying on Node.js.

Why I Don’t Like CSS Isolation in Blazor

1. Limited Reusability: CSS isolation scopes styles to individual components, which is great for preventing style leaks, but it also limits the reusability of styles across different components. This often leads to duplication or the need to create global styles anyway.

2. Increased Complexity: For complex projects, especially those with themes or shared styles, CSS isolation can introduce unnecessary complexity. Managing both isolated and global styles can be confusing and error-prone.

3. No Native Support for SASS: CSS isolation does not natively support SASS, making it difficult to use features like variables, nesting, and mixins that are essential for maintaining clean and scalable styles.

4. Debugging Challenges: Isolated styles can make debugging more difficult, especially in large projects where tracking down the source of a particular style issue can be time-consuming.

5. Global Styles Still Necessary: Even with isolation, you’ll often need global styles for things like layout, typography, and theming, leading to a hybrid approach that can be harder to manage.

How to Implement SASS in Blazor Using AspNetCore.SassCompiler

To bypass the limitations of CSS isolation and utilize SASS in your Blazor project, you can use the AspNetCore.SassCompiler NuGet package. Here’s how:

1. Install the AspNetCore.SassCompiler NuGet Package

• Open your Blazor project in Visual Studio or your preferred IDE.
• Install the AspNetCore.SassCompiler package via the NuGet Package Manager or by running the following command in the Package Manager Console:

  dotnet add package AspNetCore.SassCompiler

This package automatically compiles your Sass styles from the Source (defaults to: Styles) will automatically be compiled into .css files in the TargetFolder (defaults to: wwwroot\css) on build. You can also adjust the default configuration in the appsettings.json or sasscompiler.json, you can read more about this in the documentation.

2. Set Up Your SASS File Structure

Create a Styles folder in your Blazor project. Inside this folder, create a main.scss file. This will serve as your main SASS file where you can import other partials.

Example file structure:

BlazorApp/
└── Styles/
    ├── _component.scss
    ├── _mixins.scss
    ├── _variables.scss
    └── main.scss

Rebuild/serve the project and a css directory will appear under wwwroot with a main.css and a main.css.map file. As these files are generated with every build, you'll want to add them into your projects .gitignore file.

3. Enable the Sass Watcher

If you want the css to be rebuilt automagically, add this to the Programme.cs and the Sass watcher will be enabled.

// Add the Sass Watcher  
#if DEBUG
    builder.Services.AddSassCompiler();
#endif

Adding the #if DEBUG statement to ensures the watcher is only used during debug mode.

4. Include the Compiled CSS in Your Blazor Project

Reference the compiled CSS file in your App.razor file with the below snippet.

<link href="css/styles.css" rel="stylesheet" />

Remove the other stylesheet references, as we don't need them any more.

    <link rel="stylesheet" href="app.css" />
    <link rel="stylesheet" href="[ProjectName].styles.css" />

Note: For the purposes of this tutorial I'm keeping the bootstrap styles, in a production project this would be removed too and replaced with this week favourite SASS framework.

5. Migrate the Blazor styles to SASS

If you run the project now, you should see something that looks a lot like the following image.

We need to migrate the styles we've removed and migrate them over to SASS. At the same time we can now take advantage of SASS features like variables, mixins, nesting, and inheritance to keep your styles DRY (Don't Repeat Yourself) and maintainable.

Typically, I would do this in the following order:

1. Copy the contents of the app.css files in a _blazor.scss under components directory. Reference the new file in _component.scss.
2. Copy the contents of any isolated CSS files (ComponentName.razor.css) into their own scss files, try to follow the existing directory structure. Again referencing the new files in _component.scss
3. Go through the colours and create them as variables in _variables.scss. Its quite fun seeing the mixed uses of colour types used in the blazor sample, i converted them all to hex as I went along.
4. Do the same with any widths used in media-queries, or fonts.
5. Test and refactoring; Do all my styles look right? Can I nest some styles for better structure?

With a little work, my folder structure looked a little like this...

BlazorApp/
└── Styles/
    ├── Components/
    │   ├── Layout/
    │   │   ├── _mainLayout.scss
    │   │   └── _navManu.scss
    │   └── _blazor.scss
    ├── _component.scss
    ├── _mixins.scss
    ├── _variables.scss
    └── main.scss

And now, the site should look exactly like it did previously, but now you can go wild and add SASS to all your new features.

Conclusion

CSS isolation in Blazor has its benefits, particularly for small projects or simple component-based styling. However, for more complex applications, especially those that require advanced styling techniques and reusability, implementing SASS using the AspNetCore.SassCompiler package offers a fantastic alternative. This approach streamlines your styling process, allows you to use modern CSS features, and integrates smoothly with your Blazor project without needing to rely on external tools like Node.js.

Sample code

I've uploaded the code related to this post to a branch in my Blazor Demo repo in GitHub.