Gulp

Quick Setup

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

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.
Run npm install --global gulp-cli command. If you already installed Gulp CLI previously, you can skip this step and jump to step 3.
Navigate to the root /front directory and run npm install or to install our local dependencies listed in package.json.
Run gulp command.

Yup, that's it!

Toolkit Introduction

Please note, the use of Gulp and its advanced settings is completely optional.

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

Please read first Introduction Page to understand how File Structure is organized in Front.

Gulp Toolkit includes the following simple Gulp commands:

gulp
gulp dist
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:

Minifies any CSS files from ./src/assets/css/*
Minifies all JavaScript files from ./src/assets/js/* and concatenates to theme.min.js file
Compiles any files where gulp-file-include is used (learn more about Gulp File Include below)
Then copies all files from ./src/* (including libraries from ./node_modules/*) 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:

Does the same work as dist process above, and:
Minifies and concatenates any used CSS vendor files in HTML pages and saves as vendor.min.css into ./build/assets/css/*
Minifies and concatenates all used JavaScript vendor files in HTML pages and saves as vendor.min.js into ./build/assets/js/*
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.

Heads up!

Do more with config.js file to control gulp dist and gulp build processes:

Change directory folder and bundle file names
Exclude any css/js files from bundle files
Copy dependencies from one to another location
and so on

More detailed information of config.js options can be found on Configuration section below on this page.

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.css">

Please note, due to the technical limitation of Gulp File Include the @@autopath is not supported for @@include function inside partial files. However, you can still use @@autopath to link any asset files within partial files.

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:

Theme Files
- theme.min.css
- theme.min.js
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:

Please note, Build Mode reserved comments can be only used in .html files at ./src/* folder.

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.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 -->
              <script src="./assets/js/theme.min.js">

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/node_modules/bootstrap-icons/font/bootstrap-icons.css">
              ...
              etc.

then, it transforms into:

            
              <!-- CSS Implementing Plugins -->
              <link rel="stylesheet" href="./assets/css/vendor.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/bootstrap/dist/js/bootstrap.bundle.min.js"></script>

              <!-- JS Implementing Plugins -->
              <!-- bundlejs:vendor [@@autopath] -->
              <script src="@@autopath/assets/vendor/hs-mega-menu/dist/hs-mega-menu.min.js"></script>
              <script src="@@autopath/assets/vendor/hs-show-animation/dist/hs-show-animation.min.js"></script>
              ...
              etc.

then, it transforms into:

            
              <!-- JS Implementing Plugins -->
              <script src="./assets/js/vendor.min.js">

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.

Please note, applying any changes in ./config.js file requires to restart the Gulp.

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: {
                themeFont: "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap",
                version: "?v=1.0",
                style: {
                  color: '#377dff', // Primary Color
                  font: 'Roboto' // 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.themeFont" rel="stylesheet">

and that will be compiled into:

            
              <!-- Google Font -->
              <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&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]

Please note, compiling the SVG files or applying any changes to config.js file requires to restart the Gulp.

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",
                  ...
                ]
              },

Please note, the skipFilesFromBundle parameter only supports .css and .js file formats.

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.

As always, if things aren’t clear, we encourage you to reach us at https://htmlstream.com/contact-us for clarification.

Quick Setup

Toolkit Introduction

Gulp Commands

1. gulp:

2. gulp dist:

3. gulp build:

Heads up!

Gulp File Include

Reserved Variables

Auto Path

Overview

Example

Delete Line

Overview

Example

Build Mode Files

Theme CSS File

Overview

Example

Theme JavaScript File

Overview

Example

Vendor CSS File

Overview

Example

Vendor JavaScript File

Overview

Example

Configuration

Start Path

config code

Overview

Variables

config code

Overview

Variables in SVG files

Variables in functions

Layout Builder

config code

Overview

Properties of layoutBuilder

Skip Files from Bundle

config code

Overview

Copy Dependencies

config code

Overview

Build Folder

config code

Overview

Replace Paths to CDN

config code

Overview

Example

Directory Names

config code

Overview

File Names

config code

Overview

File Types

config code

Overview

Properties of `layoutBuilder`