How to make a Bootstrap 5 theme: basic setup

Bootstrap 5 has been recently released with new interesting features like RFS and RTL.

Here is a quick tutorial to start making your own theme. The scope of this tutorial is to create style.css from style.scss importing Bootstrap 5 without any customisation yet.

The general idea

Bootstrap 5 is mainly written in sass which gets compiled to css. And then a touch of postcss is used for autoprefix to ensure browser compatibility.
In the end, purgecss can be used to prune the unused css selectors.

Tool      From           To
----------------------------------- 
sass      styles.scss -> styles.css
postcss   styles.css  -> styles.css
purgecss  styles.css  -> styles.css

Scaffolding

Let’s start creating our base folder which will contain all our files.

mkdir bootstrap5-theme
cd bootstrap5-theme
npm init -y

At the end of these commands you should have:

bootstrap5-theme
└── package.json

Then let’s add .nvmrc to fix the node version we’re using.
In this case, we’ll go for node v16.13.2 as currently the LTS.

This is assuming you’re familiar with nvm. In case you’re not, read here about nvm.

echo '16.13.2' >> .nvmrc
nvm install

and .gitignore if you want to use git.

# ignore .DS_Store and node_modules
echo '.DS_Store' >> .gitignore
echo 'node_modules/' >> .gitignore

At the end of these commands you should have:

bootstrap5-theme
├── .nvmrc
├── .gitignore
└── package.json

We’re ready to install Bootstrap 5 now (currently the latest version is v5.1.3).

# install v5.1.3
npm i bootstrap@5.1.3

By default npm i will save the packege installed under dependencies in package.json.

# in package.json you should have
"dependencies": {
    "bootstrap": "^5.1.3"
}

We’re ready for sass now.

# install sass
npm i --save-dev node-sass
# in package.json you should have
"devDependencies": {
    "node-sass": "^7.0.1"
}

And now we can create our basic folder which will contains our styles.scss.

Now we’re copying the main file from Bootstrap 5 which is bootstrap.scss and _variables.scss which contains the variables we’ll customize later on.

mkdir scss
cp node_modules/bootstrap/scss/bootstrap.scss scss/styles.scss
cp node_modules/bootstrap/scss/_variables.scss scss/_variables.scss

At the end of this commands you should have:

bootstrap5-theme
├── node_modules
├── .nvmrc
├── .gitignore
├── package-lock.json
├── package.json
└── scss
    ├── _variables.scss
    └── styles.scss

Now, with our preferred editor we have to edit styles.scss and for every @import we should add the following path ./node_modules/bootstrap/scss/.

This will allow you to import the files from the Bootstrap package we installed with npm that now stays in node_modules/bootstrap.

Here an example of the first rows in your styles.scss:

// Configuration
@import "./node_modules/bootstrap/scss/functions";
@import "variables";
@import "./node_modules/bootstrap/scss/mixins";
@import "./node_modules/bootstrap/scss/utilities";

// Layout & components
@import "./node_modules/bootstrap/scss/root";
@import "./node_modules/bootstrap/scss/reboot";
@import "./node_modules/bootstrap/scss/type";
@import "./node_modules/bootstrap/scss/images";
@import "./node_modules/bootstrap/scss/containers";
@import "./node_modules/bootstrap/scss/grid";
@import "./node_modules/bootstrap/scss/tables";
@import "./node_modules/bootstrap/scss/forms";
Note: The only import we did not modify is @import "variables"; that is not a mistake.
The reason why is because we do want to use scss/_variables.scss we copied before as it’s the variable file we’ll modify and we’ll want to commit to our repo.

If now you try to run node-sass against styles.scss you should see the Bootstrap css as output without errors. In that case, congratulations! You just build Bootstrap 5 from sources with sass! Well done!

# cmd to quickly build Bootstrap 5
./node_modules/.bin/node-sass scss/styles.scss

Ok, we’re getting there! Now let’s add a build script to our package.json in a way we can build our Bootstrap theme with npm run build.

# In package.json
"scripts": {
    "build": "node-sass scss/styles.scss css/styles.css"
},

When you npm run build you should have:

➜ npm run build

> bootstrap5-theme@1.0.0 build
> node-sass scss/styles.scss css/styles.css

Rendering Complete, saving .css file...
Wrote CSS to /bootstrap5-theme/css/styles.css

If that is the case, congratulation again! That’s it! You did successfully installed Bootstrap 5, imported its scss files and with node-sass build styles.css.

Quick recap:

  1. we did config nvm and git using .nvmrc and .gitignore
  2. then we installed with npm bootstrap and node-sass
  3. we make a scss dir and we copied the main boostrap.scss and _variables.scss
  4. we changed the path of the import to point to node_modules in styles.scss
  5. we added the build script in package.json

There is not yet customisation, but with this scaffold, you can already see we’re in a great position to start the customisation.

So, for now, congrats for achieving the basic setup and please feel free to start playing with _variables.scss, no better way to learn.

Notes:

This post was partially inspired by bootstrap-npm-starter.