Working with Gulp

In this section, we are briefly going to see how to use gulp and the gulpfile.js.

Gulp tasks

We prepared a certain number of predefined tasks that will help you during all the development process. We will go through the gulpfile.js file to detail each one of this tasks.

Server task

//Load Previews on Browser on dev
function livePreview(done) {
  browserSync.init({
    server: {
      baseDir: options.paths.dist.base
    },
    port: options.config.port || 5000
  });
  done();
}

Gulp uses this task to create a browser-sync instance. It creates a local development server and automatically opens a browser window showing index.html.

Watch task

function watchFiles() {
  watch(`${options.paths.src.base}/**/*.html`, series(compileHTML, previewReload));
  watch(['src/scss/**/*', 'src/scss/*'], compileSCSS);
  watch(`${options.paths.src.js}/**/*.js`, series(javascriptBuild, previewReload));
  watch(`${options.paths.src.img}/**/*`, series(devImages, previewReload));
  console.log("\n\t" + logSymbols.info, "Watching for Changes..\n");
}

Gulp uses this task to watch any change you make to the HTML and Sass files. When it detects changes, it triggers other tasks that handle Sass and HTML compilation.

Clean task

function devClean() {
  console.log("\n\t" + logSymbols.info, "Cleaning dist folder for fresh start.\n");
  return del([options.paths.dist.base]);
}

Gulp uses this task to clean the dist folder, which the result of the project build. At the moment you should not see any dist folder because you didn't build the project yet. This task is also used at the beginning of the build process, to clean the folder before compiling the assets again.

Bulma task

function setupBulma() {
  console.log("\n\t" + logSymbols.info, "Installing Bulma Files..\n");
  return src([nodepath + 'bulma/*.sass', nodepath + 'bulma/**/*.sass'])
    .pipe(dest('src/sass/'));
}

gulp uses this task to copy the Bulma source file from their location in the _node-modules folder to the sass/ folder. As these assets are already copied in the project, you shouldn't need this task right now.

Assets tasks

//Concat CSS Plugins
function concatCssPlugins() {
  console.log("\n\t" + logSymbols.info, "Compiling Plugin styles..\n");
  return src([
    nodepath + 'simplebar/dist/simplebar.min.css',
    nodepath + 'plyr/dist/plyr.css',
    nodepath + 'codemirror/lib/codemirror.css',
    nodepath + 'codemirror/theme/shadowfox.css',
    'src/assets/vendor/css/*',
  ])
    .pipe(sourcemaps.init())
    .pipe(concat('app.css'))
    .pipe(sourcemaps.write('./'))
    .pipe(dest('dist/css'))
    .pipe(browserSync.stream());
}

gulp uses those tasks to copy all external assets and dependencies into the corresponding sub-folder of the dist/ folder of the production site.

Compile SCSS task

//Compile SCSS code
function compileSCSS() {
  console.log("\n\t" + logSymbols.info, "Compiling App SCSS..\n");
  return src(['src/scss/main.scss'])
    .pipe(sass({
      outputStyle: 'compressed',
      sourceComments: 'map',
      sourceMap: 'scss',
      includePaths: bourbon
    }).on('error', sass.logError))
    .pipe(autoprefixer('last 2 versions'))
    .pipe(dest('dist/css'))
    .pipe(browserSync.stream());
}

Gulp uses this task to compile the Listkit SCSS source files into a single CSS file (main.css). it then copies this file in dist/css/.

Compile HTML task

//Compile HTML partials with Panini
function compileHTML() {
  console.log("\n\t" + logSymbols.info, "Compiling HTML..\n");
  panini.refresh();
  return src('src/pages/**/*.html')
    .pipe(panini({
      root: 'src/pages/',
      layouts: 'src/layouts/',
      partials: 'src/partials/',
      helpers: 'src/helpers/',
      data: 'src/data/'
    }))
    .pipe(dest('dist'))
    .pipe(browserSync.stream());
}

Gulp uses this task to compile all the changes you make to the template HTML files. It the triggers a refresh from Panini to update your templates before rendering.

Compile JS task

function javascriptBuild() {
  // Start by calling browserify with our entry pointing to our main javascript file
  return (
    browserify({
      entries: [`${options.paths.src.js}/main.js`],
      // Pass babelify as a transform and set its preset to @babel/preset-env
      transform: [babelify.configure({ presets: ["@babel/preset-env"] })]
    })
      // Bundle it all up!
      .bundle()
      // Source the bundle
      .pipe(source("bundle.js"))
      // Then write the resulting files to a folder
      .pipe(dest(`dist/js`))
  );
}

Gulp uses this task to bundle all your custom javascript into a single compressed file served with the HTML. Gulp uses browserify and babelify with @babel/preset-env to support the ES6 syntax.

Running the project

Now that we have seen that we have a lot of ready to use tasks for gulp. While you can run some of the above tasks individually, let's now see how you can run the project.

Launching the development server

To run the project, run this command in your terminal window, at the root of the project :

pnpm dev

Here is what happens when you run pnpm dev :

• Gulp deletes the dist folder
• Then, gulp executes all assets copying and compilation tasks

Template Customization

You should now have a basic understanding of what Gulp and Panini are doing. You are now ready to setup the project to start developing. We've been talking about gulp and panini for ages but you'll quickly see how fast it is to setup your project. In your terminal window, change directory to the root of the project:

cd path/to/my/project/

Then start by building the project. Run the following command. It will also launch a development server in your browser window :

pnpm dev

When the task starts, you should be redirected to your browser showing the index.html page. That's it, your project is now running. Every change you make to the HTML or SCSS files will trigger a code compilation and a browser refresh. Really easy isn't it?

Theme colors

Every project uses 3 color variables and a set of box shadows that you can customize to control global colors across the template. There are 3 main variables :

• Primary color
• Secondary color
• Accent color

Our new example theme will use primary red (#f95c64), secondary blue (#325bff) and accent purple (#dc2dff) as the main colors (these colors are just a random example, do not use in production and pick your own colors instead). Lets create those new variables. Add this to your src/scss/abstracts/_variables.scss file :

/* ==========================================================================
Example theme variables
========================================================================== */

$primary: #f95c64;
$secondary: #325bff;
$accent: #dc2dff;

Every project component and layout element rely on these variables. Changing them will immediately impact all colors in the project.

Theme shadows

Some elements, like buttons, have colored box shadows. Box shadows inherit their colors from the 3 previously defined color variables. What is great is that you don't have anything to do. Those box shadows variables are generated for you, because they inherit the value of each one of the main colors.

//Base shadow
$base-shadow: rgba(0, 0, 0, 0.12);

//Primary box shadow
$primary-shadow-from: rgba($primary, 0.42);
$primary-shadow-to: rgba($primary, 0.2);
$primary-box-shadow:  0 14px 26px -12px $primary-shadow-from, 0 4px 23px 0px $base-shadow, 0 8px 10px -5px $primary-shadow-to;

//Secondary box shadow
$secondary-shadow-from: rgba($secondary, 0.42);
$secondary-shadow-to: rgba($secondary, 0.2);
$secondary-box-shadow:  0 14px 26px -12px $secondary-shadow-from, 0 4px 23px 0px $base-shadow, 0 8px 10px -5px $secondary-shadow-to;

//Accent box shadow
$accent-shadow-from: rgba($accent, 0.42);
$accent-shadow-to: rgba($accent, 0.2);
$accent-box-shadow:  0 14px 26px -12px $accent-shadow-from, 0 4px 23px 0px $base-shadow, 0 8px 10px -5px $accent-shadow-to;

Custom CSS Helpers

Reference the helper SCSS files to learn more about all the available custom helpers, "custom helpers" meaning they are not included in the default Bulma distribution. Please note that the Bulma spacing helpers have been removed and replaced by our own. You can explore src/scss/utilities/utilities.scss and src/scss/abstracts/helpers.scss to get a grasp on available helpers.