Customize Bootstrap Using bootstrap-sass and Gulp

 ·  · 

We are going to customize Bootstrap CSS style or theme by overriding and and compiling bootstrap-sass with Gulp.

 

1 Initialize A Project

$ mkdir customize-bootstrap-sass
$ cd customize-bootstrap-sass
$ npm init

Then install npm packages we will used later.

$ npm install gulp -g --save-dev
$ npm install bootstrap-sass --save-dev
$ npm install gulp-sass --save-dev

Now your customize-bootstrap-sass/package.json file should include following dependencies like this:

{
    ....

    "devDependencies": {
        ....
        "bootstrap-sass": "^3.3.6",
        "gulp": "^3.9.1",
        "gulp-sass": "^2.2.0"
        ....
    }

    ....
}

Explanation:

  • bootstrap-sass is the package of Bootstrap Sass source code. We're going to override some variables and rebuild the SASS source.
  • gulp-sass, package tool for Gulp to compile Sass code to CSS.

 

2 Project Folder Structure

2.1 Create New Folders

Create folder structures as follows:

customize-bootstrap-sass/
    - src/
        - scss/
            - main.scss 
    - dist/
        - css/
    - gulpfile.js
    - package.json

customize_bootstrap_folder_structure

Additionally, bootstrap-sass had been installed under node_modules folder.

bootstrap-sass-installed-path

  • Sass source files are all under node_modules/bootstrap-sass/assets/stylesheets/
  • _bootstrap.scss is the entry file. Open it you can see this file imported various source Sass codes of different Bootstrap components.

2.2 gulpfile.js

Configure gulpfile.js according to our folder structure.

2.2.1 Require Modules

The first step, require modules:

/* gulpfile.js */
var 
    gulp = require('gulp'),
    sass = require('gulp-sass');

2.2.2 src and dist

The second step, specify source folder and distribution folder.

/* gulpfile.js */
......

// source and distribution folder
var
    source = 'src/',
    dest = 'dist/';

// Bootstrap scss source
var bootstrapSass = {
        in: './node_modules/bootstrap-sass/'
    };

// Bootstrap fonts source
var fonts = {
        in: [source + 'fonts/*.*', bootstrapSass.in + 'assets/fonts/**/*'],
        out: dest + 'fonts/'
    };

// Our scss source folder: .scss files
var scss = {
    in: source + 'scss/main.scss',
    out: dest + 'css/',
    watch: source + 'scss/**/*',
    sassOpts: {
        outputStyle: 'nested',
        precison: 3,
        errLogToConsole: true,
        includePaths: [bootstrapSass.in + 'assets/stylesheets']
    }
};

Pay attention to includePaths, this will tell gulp-sass where to import Sass files.

2.2.3 Fonts Task

The third step, add a Gulp fonts task to copy bootstrap required fonts to dist folder:

/* gulpfile.js */
......

// copy bootstrap required fonts to dest
gulp.task('fonts', function () {
    return gulp
        .src(fonts.in)
        .pipe(gulp.dest(fonts.out));
});

2.2.4 Sass Task

The fourth step, compile source Sass into CSS and copy the result CSS file to dist:

/* gulpfile.js */
......

// compile scss
gulp.task('sass', ['fonts'], function () {
    return gulp.src(scss.in)
        .pipe(sass(scss.sassOpts))
        .pipe(gulp.dest(scss.out));
});

['fonts'] means sass task will depend on fonts task, before executing sass task gulp will automatically run fonts task firstly.

2.2.5 Default Task And Watch

Add default task:

/* gulpfile.js */
......

// default task
gulp.task('default', ['sass'], function () {
     gulp.watch(scss.watch, ['sass']);
});

Now the whole gulpfile.js should be:

/* gulpfile.js */
var 
    gulp = require('gulp'),
    sass = require('gulp-sass');

// source and distribution folder
var
    source = 'src/',
    dest = 'dist/';

// Bootstrap scss source
var bootstrapSass = {
        in: './node_modules/bootstrap-sass/'
    };

// fonts
var fonts = {
        in: [source + 'fonts/*.*', bootstrapSass.in + 'assets/fonts/**/*'],
        out: dest + 'fonts/'
    };

// css source file: .scss files
var scss = {
    in: source + 'scss/main.scss',
    out: dest + 'css/',
    watch: source + 'scss/**/*',
    sassOpts: {
        outputStyle: 'nested',
        precison: 3,
        errLogToConsole: true,
        includePaths: [bootstrapSass.in + 'assets/stylesheets']
    }
};

// copy bootstrap required fonts to dest
gulp.task('fonts', function () {
    return gulp
        .src(fonts.in)
        .pipe(gulp.dest(fonts.out));
});

// compile scss
gulp.task('sass', ['fonts'], function () {
    return gulp.src(scss.in)
        .pipe(sass(scss.sassOpts))
        .pipe(gulp.dest(scss.out));
});

// default task
gulp.task('default', ['sass'], function () {
     gulp.watch(scss.watch, ['sass']);
});

 

3 Build Bootstrap

Our main.scss is our Sass source file, also the Sass entry file. Import Bootstrap entry file in main.scss:

/* main.scss */
@import "bootstrap";
@import "bootstrap/theme";
  • The first @import will import <scss.sassOpts.includePaths>/_bootstrap.scss; (Do you still remember includePaths that you should pay attention to?)
  • The second @import will import <scss.sassOpts.includePaths>/bootstrap/_theme.scss

Run command:

$ cd customize-bootstrap-sass
$ gulp

This command will compile our main.scss to CSS file and copy it to dist/css/main.css.

The result file: dist/css/main.cssis exact the built Bootstrap CSS file.

 

4 Customize CSS Style

There are two main places you can customize Bootstrap.

4.1 Build Only The Components You Need

Open the Bootstrap Sass entry file:

$ cd customize-bootstrap-sass
$ cat node_modules/bootstrap-sass/assets/stylesheets/_bootstrap.scss

You will discover that this file imported various Bootstrap components. So we can create a customized entry file and import components we wanted only.

$ cd customize-bootstrap-sass
$ cp node_modules/bootstrap-sass/assets/stylesheets/_bootstrap.scss ./src/scss/_bootstrap-custom.scss

In this _bootstrap-custom.scss file, you can feel free to comment out those components(lines) you do not want to include.

Then modify our entry main.scss, import _bootstrap-custom.scss instead.

/* main.scss */
@import "bootstrap-custom";
@import "bootstrap/theme";

Compile and build:

$ cd customize-bootstrap-sass
$ gulp

4.2 Override Variables

The style of Bootstrap components in a theme are determined by variables. These variables are defined in _variables.scss file.

Take a glance at this file:

$ cd customize-bootstrap-sass
$ cat node_modules/bootstrap-sass/assets/stylesheets/bootstrap/_variables.scss

Notice that there is a !default directive at the end of each declaration line.

This directive means: current variable will be defined and set value ONLY if it doesn’t be defined or have a value already. In brief: "If not set value yet, set it, else, keep old value!".

So if we assign our own value to those variables BEFORE importing Bootstrap, we can override them.

We need a copy of _variables.scss in our Sass source file folder.

$ cd customize-bootstrap-sass
$ cp node_modules/bootstrap-sass/assets/stylesheets/bootstrap/_variables.scss ./src/scss/_override-variables.scss

Now override what you want in src/scss/_override-variables.scss, delete lines you don't want to customize, modify lines you want to override:

/* src/scss/_override-variables.scss */
$body-bg: #dff0d8;
$link-color: pink;
$font-size-base: 18px;

Then import it in main.scss before importing bootstrap:

/* main.scss */
@import "override-variables";

@import "bootstrap";
@import "bootstrap/theme";

At last, recompile our Sass into CSS file:

$ cd customize-bootstrap-sass
$ gulp

The overridden Bootstrap theme CSS file now is ready: dist/css/main.css.

 

5 Sample Codes

Demo project is available on GitHub.

bootstrapsassgulp