Setting up Bootstrap 4 SASS with ASPNET Core
Tags: dotnet, bootstrap, aspnet, sass
Published: 2020-10-17 14:15:31

The default ASPNET MVC template comes with [Bootstrap 4](https://getbootstrap.com/) out-of-the-box. This is an already compiled version of Bootstrap. To [customize](https://getbootstrap.com/docs/4.5/getting-started/theming/) 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](https://www.nuget.org/packages/bootstrap.sass/) package, but this wasn't working for me. NuGet is not equipped as a Frontend Package manager [so it seems](https://github.com/twbs/bootstrap/issues/16692#issuecomment-117922208).

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](https://www.npmjs.com/) 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.

{% gist https://gist.github.com/robinvanderknaap/126e0a765c6c129b554f5ddadbaaead1 %}

`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.

{% gist https://gist.github.com/robinvanderknaap/b08123437612edd3e298d8a5f1d21a80 %}

Add the following at the top of site.scss

{% gist https://gist.github.com/robinvanderknaap/45c294474f6e45aeb3ae30a23e538ff8 %}

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

{% gist https://gist.github.com/robinvanderknaap/255549c72278a399d50c6c9b436f0714 %}

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`

{% gist https://gist.github.com/robinvanderknaap/788ff1c05e0da05b3ad79313a78f0122 %}

## 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:

{% github https://github.com/robinvanderknaap/aspnet-bootstrap-sass no-readme %}

<span>Cover photo by <a href="https://unsplash.com/@swimstaralex?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Alexander Sinn</a> on <a href="https://unsplash.com/s/photos/code?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></span>