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:
- Download and install Node.js , which we use to manage our dependencies. If Node.js is already installed in your machine and jump to step 2.
- Run
npm install --global gulp-cli
command. If you already installedGulp CLI
previously, you can skip this step and jump to step 3. - Navigate to the root
/front
directory and runnpm install
or to install our local dependencies listed inpackage.json
. - 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:
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 totheme.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./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:
- 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.min.css">
@@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:
.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.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/node_modules/bootstrap-icons/font/bootstrap-icons.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/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 -->
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.
./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=Inter:wght@400;600&display=swap",
version: "?v=1.0",
style: {
color: '#377dff', // Primary Color
font: 'Inter' // 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=Inter: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 [@@F]RGBA[color, opacity]
function. The opacity values can be between 0.1
to 1
same like in SASS.
[@@F]RGBA[@@vars.style.color,.5]
Make color lighter with [@@F]Lighten[color, value]
function. The larger the integer value, the lighter.
[@@F]Lighten[@@vars.style.color, 50]
Make color darker with [@@F]Darken[color, value]
function. The larger the integer value, the lighter.
[@@F]Darken[@@vars.style.color, 50]
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",
...
]
},
.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.