Gulp

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

Quick Setup

Installing and running Gulp is super easy in Unity, 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 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 /Unity 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

Unity 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 Unity'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 Unity's Gulp Toolkit features with detailed information and examples.

The following files powers the Gulp Toolkit:

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

Unity 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 Unity -->
              <!-- 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 Unity -->
              <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 Unity -->
              <!-- 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 Unity -->
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>
              ...
              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=Inter:wght@400;500;600&display=swap",
                version: "?v=1.0",
                style: {
                  color: '#0ABF53', // 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 Unity:

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

and that will be compiled into:

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

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.