Gulp

Learn how to use and automate your time-consuming tasks in your development workflow with Front's powerful Gulp Toolkit extension.

Quick Setup

Installing and running Gulp is super easy in Front, please follow these steps and you should be ready to rock:

  1. Download and install Node.js , which we use to manage our dependencies. If Node.js is already installed in your machine, please make sure the installed version is v12.x and jump to step 2.
  2. Run npm install --global gulp-cli command. If you already installed Gulp CLI previously, you can skip this step and jump to step 3.
  3. Navigate to the root /front-dashboard directory and run npm install or to install our local dependencies listed in package.json.
  4. Run gulp command.

Yup, that's it!

Toolkit Introduction

Front uses NPM scripts including custom JavaScript scripts written by Htmlstream Team for its build system. The goal was to utilize the power of Gulp to achieve maximum automation in static HTML Templates to help developers saving precious time for any kind of manual tasks and file changes.

Briefly speaking Front's Gulp Toolkit able to compile codes, minification js/css files, combine js/css files, auto path detection, pasting variables over HTML and SVG files, preparing build package and lots of others. On this page we will cover all Front's Gulp Toolkit features with detailed information and examples.

The following files powers the Gulp Toolkit:

  • gulpfiles
    • build.js
    • core.js
    • dist.js
    • paths.js
    • preview.js
    • watch.js
    • svg-compiler.js
  • config.js
  • gulpfile.js
  • package-lock.json
  • package.json

Heads up! The main core file for development is config.js and you don't need to worry about the rest files. We highly don't recommend touching the rest files since all settings included inside config.js file. Learn more below at Configuration section for all available setting options.

Gulp Commands

Gulp Toolkit includes the following simple Gulp commands:

  1. gulp
  2. gulp dist
  3. gulp build

On top of it, any Gulp or NPM commands can be also used.


1. gulp:

gulp is the main command to start compiling and watching SASS / HTML files. When you run gulp it starts a server poping up a new tab in your default browser. Any changes from the source files are instantly compiled on the fly and updates browser tab instantly with the help of Live Reload (Browsersync).


2. gulp dist:

gulp dist command compiles and copies all files from ./src/* folder into ./dist/* folder and prepares production files. Basically, it copies whole complied assets into ./dist/* folder with minified theme css/js files. Under the hood it performs the following processes:

  1. Minifies any CSS files from ./src/assets/css/*
  2. Minifies all JavaScript files from ./src/assets/js/* and concatenates to theme.min.js file
  3. Compiles any files where gulp-file-include is used (learn more about Gulp File Include below)
  4. Then copies all files from ./src/* (including libraries from ./assets/vendor/*) and saves into ./dist/*

3. gulp build:

gulp build command prepares performance ready fully production files of your project into ./build/* folder by automatically detecting all used asset sources from HTML pages. Under the hood it performs the following processes:

  1. Does the same work as dist process above, and:
  2. Minifies and concatenates any used CSS vendor files in HTML pages and saves as vendor.min.css into ./build/assets/css/*
  3. Minifies and concatenates all used JavaScript vendor files in HTML pages and saves as vendor.min.js into ./build/assets/js/*
  4. Automatically detects any used jpg|png|svg|mp4|webm|ogv|json file formats from HTML pages and copies to relevant folders

The main difference between dist and build processes, build sorts out what's used on the pages and prepares only used asset sources, while dist just copy and pastes the compiled and generated files into ./dist/ folder.


Gulp File Include

Front uses Gulp File Include NPM package to provide convenience for development. With the help of Gulp File Include most common used components (e.g. header, sidebar, footer etc.) can be globally updated at once. It's like PHP include function when changes made from the single file - it updates all pages instantly where the component is used.

All used partials can be found at ./src/partials/* and new ones can be easily added. Create new .html partial file inside partials/ folder and use with @@include in your HTML pages. Please read the official documentation for more options and details. In addition, config.js file includes variables with other options. More information can be obtained at the Configuration section below.

Reserved Variables

On top of Gulp File Include, the usage of variables are extended in Gulp Toolkit to perform some specific tasks. Read below for more details and use cases:

Auto Path
Parameters Description
@@autopath Automatically determines the path to the assets files, regardless of the nesting level of the HTML file

Overview

Since @@autopath is used within ./src/ folder, it's default path starts at ./src/ directory. The default directory name can be changed with the help of directoryNames property from config.js file if needed.

Example

Considering the file is located at the roof of ./src/ folder:

                
                  <link rel="stylesheet" href="@@autopath/assets/css/theme.css">
                
              

Will be compiled to:

                
                  <link rel="stylesheet" href="./assets/css/theme.min.css">
                
              
Delete Line
Parameters Description
@@deleteLine Deletes a line in both dist & build processes.
@deleteLine:dist Deletes a line only in dist process.
@deleteLine:build Deletes a line only in buld process.

Overview

Delete lines are usually used for comments while bundling files into one in build process.

Example
                
                  <!-- JS Global Compulsory @@deleteLine -->
                
              
                
                  <!-- JS Global Compulsory @@deleteLine:dist -->
                
              
                
                  <!-- JS Global Compulsory @@deleteLine:build -->
                
              

Build Mode Files

The Build Modes Files generates two type of bundle files - .css and .js files in build process:

  1. Theme Files
    • theme.min.css
    • theme.min.js
  2. Vendor Files
    • vendor.min.css
    • vendor.min.js

Any generated output file names can be changed from fileNames property in config.js file.

In order to build these type of files the build process includes reserved comments with special syntaxes in Gulp Toolkit. Read below for more details and examples:

Theme CSS File
Reserved Comment Description Gulp Mode
<!-- bundlecss:theme [@@autopath] --> Generates Theme CSS file as theme.min.css dist, build

Overview

Minifies theme.css file into min.theme.css file and replaces in all HTML pages.

Example

Placing bundlecss:theme reserved comment in HTML file:

                
                  <!-- CSS Front -->
                  <!-- bundlecss:theme [@@autopath] -->
                  <link rel="stylesheet" href="@@autopath/assets/css/theme.css">
                
              

now, the theme.css file is minified and replaced with theme.min.css file automatically in HTML page(s):

                
                  <!-- CSS Front -->
                  <link rel="stylesheet" href="./assets/css/theme.min.min.css">
                
              
Theme JavaScript File
Reserved Comment Description Gulp Mode
<!-- bundlejs:theme [@@autopath] --> Generates Theme JavaScript bundle file as theme.min.js dist, build

Overview

Concatenates and minifies all .js files from .src/assets/js/* folder in gulp dist process and saves as theme.min.js file, then replaces in all HTML pages.

The gulp build process does the same process as gulp dist but instead of processing all .js files, it selects only used JavaScript files from HTML pages.

Example

Placing bundlejs:theme reserved comment in HTML file:

                
                  <!-- JS Front -->
                  <!-- bundlejs:theme [@@autopath] -->
                  <script src="@@autopath/assets/js/hs.core.js"></script>
                  <script src="@@autopath/assets/js/hs.file-1.js"></script>
                  <script src="@@autopath/assets/js/hs.file-2.js"></script>
                  <script src="@@autopath/assets/js/hs.file-3.js"></script>
                  ...
                  etc.
                
              

then, it transforms into:

                
                  <!-- JS Front -->
                
              
Vendor CSS File
Reserved Comment Description Gulp Mode
<!-- bundlecss:vendor [@@autopath] --> Generates Vendor CSS bundle file as vendor.min.css build

Overview

Concatenates and minifies all used CSS library files in HTML pages and saves as vendor.min.css file, then replaces in all HTML pages.

Example

Placing bundlecss:vendor reserved comment in HTML file:

                
                  <!-- CSS Implementing Plugins -->
                  <!-- bundlecss:vendor [@@autopath] -->
                  <link rel="stylesheet" href="@@autopath/assets/vendor/icon-set/style.css">
                  <link rel="stylesheet" href="@@autopath/node_modules/select2/dist/css/select2.min.css">
                  <link rel="stylesheet" href="@@autopath/node_modules/chart.js/dist/Chart.min.css">
                  ...
                  etc.
                
              

then, it transforms into:

                
                  <!-- CSS Implementing Plugins -->
                  <link rel="stylesheet" href="./assets/css/vendor.min.min.css">
                
              
Vendor JavaScript File
Reserved Comment Description Gulp Mode
<!-- bundlejs:vendor [@@autopath] --> Generates Theme JavaScript bundle file as vendor.min.js build

Overview

Concatenates and minifies only used JavaScript library files in HTML pages and saves as vendor.min.js file, then replaces in all HTML pages.

Example

Placing bundlejs:vendor reserved comment in HTML file:

                
                  <!-- JS Global Compulsory @@deleteLine:build -->
                  <script src="@@autopath/node_modules/jquery/dist/jquery.min.js"></script>
                  <script src="@@autopath/node_modules/jquery-migrate/dist/jquery-migrate.min.js"></script>
                  <script src="@@autopath/node_modules/bootstrap/dist/js/bootstrap.bundle.min.js"></script>

                  <!-- JS Implementing Plugins -->
                  <!-- bundlejs:vendor [@@autopath] -->
                  <script src="@@autopath/assets/vendor/hs-unfold/dist/hs-unfold.min.js"></script>
                  <script src="@@autopath/assets/vendor/hs-form-search/dist/hs-form-search.min.js"></script>
                  <script src="@@autopath/node_modules/select2/dist/js/select2.full.min.js"></script>
                  ...
                  etc.
                
              

then, it transforms into:

                
                  <!-- JS Implementing Plugins -->
                
              

Configuration

All configuration options can be found inside the ./config.js file. As mentioned above, you don't need to worry about the rest Gulp files. We heighly don't recommend touching the other Gulp related files, since all settings included inside this config.js file - unless there are cases where project needs to be extended the Gulp Toolkit further. To keep the development process as much as flexible, the configuration options are provided. Read below for more detailed descriptions and examples.

Start Path

Parameters String Description Default Gulp Mode
startPath string Start path when launching a Gulp "/index.html" default

config code
                
                  startPath: "/index.html",
                
              
Overview

When you run gulp command it opens up index.html page on your browser from ./src/* folder. You can set the Starting page to any page from the ./src/* folder.

Variables

Parameters String Description Default Gulp Mode
vars object Variables that can be used in HTML pages and SVG files {} all

config code
                
                  vars: {
                    googleFont: "https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600&display=swap",
                    version: "?v=1.0",
                    style: {
                      color: '#134ba4', // Primary Color
                      font: 'Open Sans' // Primary Font
                    }
                  },
                
              
Overview

Any new variables can be added inside var {..} object and used in HTML pages with double at @@vars. Variables are very practical to use when there are some repetitive values which should be updated at once in all pages. It helps to avoid manual changes from each HTML pages and gives handy automation.

Let's take an example of Google Fonts which is used in all HTML pages in Front:

                
                  <!-- Google Font -->
                  <link href="@@vars.googleFont" rel="stylesheet">
                
              

and that will be compiled into:

                
                  <!-- Google Font -->
                  <link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600&display=swap" rel="stylesheet">
                
              

In a same way, any variables can be passed to HTML page and used as above example.

Variables in SVG files

In Front, we extended the usage of variables even further and added compatibility to SVG files. The SVG files where variables are used, should be saved inside svg-src/* folder instead of svg/* folder at ./src/assets/*. Any SVG files at ./src/assets/svg-src/* will be compiled and saved into svg/* folder.

The examples can be found in any SVG files at ./src/assets/svg-src/* folder.

Variables in functions

In addition, we added color functions that can be used inside html and svg files.

Convert HEX color to rgba with gulpRGBA[color, opacity] function. The opacity values can be between 0.1 to 1 same like in SASS.

                
                  gulpRGBA[@@vars.style.color,.5]
                
              

Make color lighter with gulpLighten[color, value] function. The larger the integer value, the lighter.

                
                  gulpLighten[@@vars.style.color, 50]
                
              

Make color darker with gulpDarken[color, value] function. The larger the integer value, the lighter.

                
                  gulpDarken[@@vars.style.color, 50]
                
              

Layout Builder

Parameters String Description Default Gulp Mode
layoutBuilder object Layout builder to customize look and feel of siderbar and navbar {} all

config code
                
                  layoutBuilder: {
                    skin: 'default', // default, dark, light
                    header: {
                      layoutMode: 'default', // default, single, double
                      containerMode: 'container' // container, container-fluid
                    },
                    sidebarLayout: 'default', // default, compact, mini
                  },
                
              
Overview

The Gulp Layout Builder shares the same features as the live Builder example. Furthermore, over 15 layout examples can be found on Layouts page.

Properties of layoutBuilder

Easily customize the Layouts and Navbar Skins by changing the following property options:

Property Option Notes
skin default | dark | light Skins are not applied to Double Line Header option.
header.layoutMode default | single | double When header options are set - the sidebarLayout will not be applied. It means the pages will not have Sidebar as they will be replaced with headers.
header.containerMode container | container-fluid To change the Container Mode, please first set header.layoutMode to single or double.
sidebarLayout default | compact | mini Make sure to set header.layoutMode to default when using sidebarLayout options.

Skip Files from Bundle

Parameters String Description Default Gulp Mode
skipFilesFromBundle array Skip CSS & JavaScript files from bundle files (e.g. vendor.min.css) [] dist, build

config code
                
                  skipFilesFromBundle: {
                    dist: [
                      "assets/js/hs.chartjs-matrix.js",
                    ],

                    build: [
                      "assets/css/docs.css",
                      "assets/vendor/icon-set/style.css",
                      "assets/js/hs.chartjs-matrix.js",
                      ...
                    ]
                  },
                
              
Overview

Sometimes projects require to keep some files separately from concatenated bundle files. For that, there might be lots of reasons during the project development. The skipFilesFromBundle property helps to control what files should be avoided from the bundle files while gulp dist and gulp build processes.

Copy Dependencies

Parameters String Description Default Gulp Mode
dependencies object Copy/Paste files and folders into different path {} dist, build

config code
                
                  copyDependencies: {
                    dist: {
                      "*assets/js/theme-custom.js": ""
                    },

                    build: {
                      "*assets/js/theme-custom.js": ""
                    }
                  },
                
              
Overview

Gulp Toolkit while processing dist and build packages, it reads the source code from HTML files to detect what asset files are used. There's are some scenarios when asset files are not linked through HTML files and in order to save those files into generated packages copyDependencies property can be helpful and used.

Below, a few scenarios are given:

  • When files are not used in HTML pages like theme-custom.js in our case, as it's created for end user to include the custom JavaScript codes. However, we still need to provide the file in .dist/* folder and with the help of copyDependencies property it's copied and pasted into ./dist/* folder.
  • When asset files are included in the bundle packages but their sources are linked through CSS files like Font Files, Background Images and so on. Since, Gulp Toolkit reads files from HTML files, it can not detect asset files if they are linked through CSS or JavaScript files.
  • Or you may want include some asset files for some purpose in the generated packages even if they are not used on the pages.

Build Folder

Parameters String Description Default Gulp Mode
buildFolder string An option to set custom folder name for build process "" build

config code
                
                  buildFolder: "", // my-project folder
                
              
Overview

By default, a gulp build function processes the whole project from ./src/* folder when the option is set to empty "". However, a custom folder name like my-project can be added and set for build process.

Here is how it looks when you set my-project folder:

                
                  buildFolder: "my-project",
                
              

Now, when gulp build command is run, it only checks all HTML pages from ./src/my-project/* and prepares a ./build/my-project/* folder with relevant assets files.

Replace Paths to CDN

Parameters String Description Default Gulp Mode
replacePathsToCDN object Replace an asset paths in HTML to CDN {} build

config code
                
                  replacePathsToCDN: {},
                
              
Overview

Sometimes to enhance the site speed (page load), often CDN links are used. With the help of replacePathsToCDN property, the library asset paths can be replaced with the CDN links in ./build/* folder.

Example
                
                  replacePathsToCDN: {  "assets/vendor/example/example.min.css": "https://cdn.example.com/example/css/example.min.css" }
                
              

Directory Names

Parameters String Description Default Gulp Mode
directoryNames object Change directory folder names {} -

config code
                
                  directoryNames: {
                    src: "./src",
                    dist: "./dist",
                    build: "./build"
                  },
                
              
Overview

From time to time projects might have different or existing File Structure and directoryNames options allows to change folder names for build processes.

Let's say if build: "./build" is changed to build: "./my-project" the gulp build process will generate ./my-folder folder instead of ./build/ folder.

File Names

Parameters String Description Default Gulp Mode
fileNames object Change bundle file names {} dist, build

config code
                
                  fileNames: {
                    dist: {
                      js: "theme.min.js",
                      css: "theme.min.css"
                    },

                    build: {
                      css: "theme.min.css",
                      js: "theme.min.js",
                      vendorCSS: "vendor.min.css",
                      vendorJS: "vendor.min.js",
                    }
                  },
                
              
Overview

A property with options to control bundle fine names in build processes. For example, theme.min.js can be changed to myBrandName.min.js in ./dist/* and ./build/* folders.

File Types

Parameters String Description Default Gulp Mode
fileType string Files types that will be copied to the ./build/* folder "" build

config code
                
                  fileTypes: "jpg|png|svg|mp4|webm|ogv|json",
                
              
Overview

Since the Gulp Toolkit in build process able to automatically detect and prepare the asset files which are used in HTML pages, it should know which file types to be looked. If other file types are you used in HTML pages, the file types should be specified at fileTypes property.