Build a Drupal 8 Bootstrap Subtheme with SCSS, Gulp

1. About drupal 8 boostrap theme.

According to BuiltWith.com, as of November 2017, almost 16 million websites use the Bootstrap library. And w3techs says it's used by 21.4% of all public internet sites. For sure that is a lot.

This makes Bootstrap the top JS Framework worldwide and the second most popular JS library ever used, right after jQuery, which is used across 72% of the web. This means that there are a lot of docs and examples out there to use as a guide.

Thousands of developers know Bootstrap and work with it every day. And because Bootstrap is not Drupal-specific, you can use Bootstrap for your Drupal theme and your other non-Drupal projects. Front-end developers who know Bootstrap can be more easily on-boarded on your project if you go with Bootstrap as a base theme.

2. Install themes Bootstrap for Drupal.

• CD into your project root in terminal and enter the commands as explained below
• cd drupalroot
• composer require drupal/bootstrap
• Go to the "Appearance" tab.
• Click "Install and set as default" next to Bootstrap.
• Go to Structure > Block layout.
• Ensure the blocks are placed in the correct locations.

3. Create subtheme Bootstrap

Drupal 8 Bootstrap comes loaded with two “starterkit” themes for you to create a child or subtheme with. You can find them in drupalroot/themes/contrib/bootstrap/starterkits . For this, you’ll want to copy the sass theme and paste it directly into the themes folder at drupalroot/themes/custom . Rename the folder to your theme name, so the path should look something like drupalroot/themes/custom/mytheme , where mytheme is the machine name of your theme.

We need to renaming everything in the theme to match mytheme . Here’s the hit list of things to rename and otherwise alter inside of the folder drupalroot/themes/custom/mytheme , changing THEMENAME to your theme’s name:

• config/install/THEMENAME.settings.yml to config/install/mytheme.settings.yml Key to note in this file is the cdn_provider: '' setting that disables the Drupal 8 Bootstrap theme’s automatic use of a CDN.
• config/schema/THEMENAME.schema.yml to config/schema/mytheme.schema.yml Make sure you update the three spots where THEMENAME and THEMETITLE appear in this file as well.
• THEMENAME.libraries.yml to mytheme.libraries.yml
• THEMENAME.starterkit.yml to mytheme.info.yml Note that starterkit changes to info. Edit this file to set your theme’s name and description. Finally be sure to update the two THEMENAME instances in the libraries section.
• THEMENAME.theme to mytheme.theme

With those files altered, you should have a working Drupal 8 Bootstrap subtheme. Navigate on your Drupal site to /admin/appearance, scroll down the page and click ‘Install and set as default’ on your new theme.

4. Put SASS Bootstrap in subtheme

Download a copy of Bootstrap SASS. There’s also a link directly to the download on the Bootstrap Getting Started page, under the heading Download > SASS.

When you decompress the Bootstrap SASS archive, the only parts you want are in the assets folder. Pick up everything in that folder and paste it into your new theme’s bootstrap folder at drupalroot/themes/custom/mytheme/bootstrap.

5. Config Gulp

• First, install gulp globally. To do this open the terminal (or equivalent command line tool) and type: sudo npm install -g gulp (you may need to install node.js before you can run this command).
• In finder, navigate to your theme folder and create a new file named “package.json”.
• Open “package.json” in your text editor and paste the following:

{
  "name": "mytheme",
  "version": "1.0.0",
  "description": "",
  "main": "gulpfile.js",
  "devDependencies": {
    "browser-sync": "^2.18.3",
    "gulp": "^3.9.1",
    "gulp-autoprefixer": "^4.0.0",
    "gulp-beautify": "^2.0.1",
    "gulp-imagemin": "^3.3.0",
    "gulp-jshint": "^2.0.4",
    "gulp-load-plugins": "^1.5.0",
    "gulp-notify": "^3.0.0",
    "gulp-sass": "^3.1.0",
    "gulp-sourcemaps": "^2.6.0",
    "gulp-uglify": "^3.0.0",
    "jshint-stylish": "^2.2.1"
  },
  "scripts": {
    "gulp": "Sass processing and BrowserSync"
  },
  "author": "",
  "license": "ISC"
}

Save the file.

• In the terminal navigate to your theme folder using the cd command. Once you are inside the theme folder enter the following command: npm install
• Return to finder and create a new file in your theme folder called “gulpfile.js”.
• Open “gulpfile.js” in your text editor and paste the following:

/*global -$ */
'use strict';
var gulp = require('gulp');
var $ = require('gulp-load-plugins')();
var browserSync = require('browser-sync');
var reload = browserSync.reload;
var sass = require('gulp-sass');

// Error notifications
var reportError = function(error) {
  $.notify({
    title: 'Gulp Task Error',
    message: 'Check the console.'
  }).write(error);
  console.log(error.toString());
  this.emit('end');
}

// Sass processing
gulp.task('sass', function() {
  return gulp.src('scss/**/*.scss')
      .pipe($.sourcemaps.init())
      // Convert sass into css
      .pipe($.sass({
        outputStyle: 'nested', // libsass doesn't support expanded yet
        precision: 10
      }))
      // Show errors
      .on('error', reportError)
      // Autoprefix properties
      .pipe($.autoprefixer({
        browsers: ['last 2 versions']
      }))
      // Write sourcemaps
      // .pipe($.sourcemaps.write())
      // Save css
      .pipe(gulp.dest('css'))
      .pipe(browserSync.reload({
        stream: true
      }));
});

// process JS files and return the stream.
gulp.task('js', function () {
  return gulp.src('scripts/**/*.js')
      .pipe(gulp.dest('scripts'));
});

// Optimize Images
gulp.task('images', function() {
  return gulp.src('images/**/*')
      .pipe($.imagemin({
        progressive: true,
        interlaced: true,
        svgoPlugins: [{
          cleanupIDs: false
        }]
      }))
      .pipe(gulp.dest('images'));
});

// JS hint
gulp.task('jshint', function() {
  return gulp.src('scripts/*.js')
      .pipe(reload({
        stream: true,
        once: true
      }))
      .pipe($.jshint())
      .pipe($.jshint.reporter('jshint-stylish'))
      .pipe($.notify({
        title: "JS Hint",
        message: "JS Hint says all is good.",
        onLast: true
      }));
});

// Beautify JS
gulp.task('beautify', function() {
  gulp.src('scripts/*.js')
      .pipe($.beautify({indentSize: 2}))
      .pipe(gulp.dest('scripts'))
      .pipe($.notify({
        title: "JS Beautified",
        message: "JS files in the theme have been beautified.",
        onLast: true
      }));
});

// Compress JS
gulp.task('compress', function() {
  return gulp.src('scripts/*.js')
      .pipe($.sourcemaps.init())
      .pipe($.uglify())
      .pipe($.sourcemaps.write())
      .pipe(gulp.dest('scripts'))
      .pipe($.notify({
        title: "JS Minified",
        message: "JS files in the theme have been minified.",
        onLast: true
      }));
});


// BrowserSync
gulp.task('browser-sync', function() {
  //watch files
  var files = [
    'scss/*.scss',
    'images/**/*',
    'templates/**/*.twig'
  ];
  //initialize browsersync
  browserSync.init(files, {
    proxy: "http://mysite.dev" // BrowserSync proxy, change to match your local environment
  });
});


// Default task to be run with `gulp`
gulp.task('default', ['sass', 'browser-sync'], function() {
  gulp.watch("scss/**/*.scss", ['sass']);
  gulp.watch("scripts/**/*.js", ['js']);
});

Save the file.

6. Finish

 Once you are inside the theme folder enter the following command: gulp