Setting up Bootstrap 4 SASS with ASPNET Core

#dotnet #bootstrap #aspnet #sass

The default ASPNET MVC template comes with Bootstrap 4 out-of-the-box. This is an already compiled version of Bootstrap. To customize the look and feel of Bootstrap elements, you need be able to override the default values of Bootstrap and compile Bootstrap from the SASS source.

Setting up Bootstrap with ASPNET Core was not that obvious to me. I've tried using the Bootstrap.sass package, but this wasn't working for me. NuGet is not equipped as a Frontend Package manager so it seems.

This articles describes how to setup Bootstrap 4 SASS in your ASPNET Core project using the following techniques:

NPM as package manager for frontend packages
Webpack for compiling SASS files and creating and minifying the CSS and JS bundles.
Setup Webpack as build task in .csproj file.

New ASPNET MVC project

Create a new ASPNET MVC project with your favorite IDE or use terminal/cmd/powershell:

dotnet new mvc --name AspNetBootstrapSass

Run the project from your IDE or from the commandline

cd AspNetBootstrapSass
dotnet run

If everything is working correctly you should see the default ASPNET welcome page in your browser.

Remove distribution version of Bootstrap

A distribution version of Bootstrap is already included in the template. However, we want to compile Bootstrap ourselves from the SASS source. Therefore, we will first remove Bootstrap (and also jquery) from the project.

Remove wwwroot/lib/bootstrap.
Remove wwwroot/lib/jquery.

Remove the links to all stylesheets in Views/Shared/_Layout.cshtml:

<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
<link rel="stylesheet" href="~/css/site.css" />

Replaced them with a link to our CSS bundle, which we will create later:

<link rel="stylesheet" href="~/dist/bundle.css" />

Remove Bootstrap, jQuery and site.js scripts:

<script src="~/lib/jquery/dist/jquery.min.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>

Replace them with our yet to be created javascript bundle:

<script src="~/dist/bundle.js" asp-append-version="true"></script>

Add frontend packages with NPM

We will be using NPM to import the packages we need. I'm assuming NodeJS and NPM are already installed on your system. Add the following package.json to the project root folder.

Package.json contains two dependencies: Bootstrap and jQuery, jQuery is a dependency of Bootstrap. Webpack and a number of SASS related preprocessors are included as dev dependencies. We will need those to compile the SASS sources.

Package.json also contains some scripts, build and production, which we will use later to start the Webpack build process.

Run npm install to install all packages.

npm install

We now have bootstrap in the node_modules folder (never add this folder to version control). We can now reference the bootstrap.scss file from our custom SCSS file.

Setup SASS files

We already have a css folder in our wwwroot. Let's rename this to scss. Also rename site.css to site.scss. Remember, a CSS file is always a valid SCSS file.

Also create a file called _variables.scss. This will contain our Bootstrap overrides (the background color and some theme colors are overridden as an example). It needs to be imported before Bootstrap is imported.

Add the following at the top of site.scss

What is happening here? We are importing _variables.scss containing our Bootstrap overrides. After that we are importing Bootstrap itself. Everything below that is our own custom CSS/SCSS.

Configure Webpack

To create the CSS and JS bundles we referenced in _Layout.cshtml we need to configure Webpack. Add the following webpack.config.js to the project root folder

I'm not going to dive into the specific Webpack details here. Important is that in production mode, CSS and JS bundles are minified, in development mode the bundles are still readable.

To run Webpack, we can call one of the scripts we defined in package.json

npm run build

The result can be found in wwwroot\dist. We find 2 files: bundle.css and bundle.js. We have referenced these files already in _Layout.cshtml.

For production mode with minified bundles run:

npm run production

Adding Webpack build to project file

If you don't want run npm build every time you make a change to your SASS files, you can automate this step by adding the command to your project file.

Add the following snippet to AspNetBootstrapSass.csproj

Conclusion

Above setup enables you to customize your Bootstrap distribution to your likings and also enables you to use SASS within your MVC project. You can find the example project here: