Skip to main content

Nunjucks based UI starter kit

How to setup a starter kit for markup and CSS authoring.

May 03rd, 2019
The Design team at Synergy-IT work on static HTML/CSS files in the initial stages of a project either to prototype ideas or to develop static UI for the developers to build on. So we (design team) worked on a starter kit for such HTML and CSS authoring projects.


You should have Node.js installed. The LTS (long term support) version is recommended.

Use gulp to automate HTML and CSS build steps, as well as for other things. It is available as a Node.js package and can be installed via npm (the default package manager for Node.js):

# Install gulp-cli as a global package 
$ npm install gulp-cli -g

Other npm package dependencies are listed in package.json. You can install them via:

# Make sure you are in the same directory as package.json
$ npm install

The above command will create a node_modules/ directory. (It is ignored in version control via .gitignore.)

More information about npm can be found in its official docs.

File structure

├── public/ │   ├── assets/ │   │   ├── css/ │   │   │   └── style.css │   │   ├── fonts/ │   │   ├── img/ │   │   └── js/ │   └── *.html ├── src/ │   ├── assets/ │   │   ├── fonts/ │   │   ├── icons/ │   │   │   └── *.svg │   │   ├── img/ │   │   └── js/ │   ├── pages/ │   │   ├── templates/ │   │   │   ├── macros/ │   │   │   │   └── *.njk │   │   │   ├── partials/ │   │   │   │   └── *.njk │   │   │   └── layout.njk │   │   └── *.njk │   └── scss/ │   ├── blocks/ │   ├── vendor/ │   ├── *.scss │   └── style.scss ├── ├── gulpfile.js ├── package-lock.json └── package.json

The src/ directory contains all the source files and assets. The public/ directory contains the generated HTML and CSS files, as well as copied assets (fonts, images, JS etc.)

{package|package-lock}.json files are used by npm install for installing the required packages.

gulpfile.js includes the tasks for building HTML pages and CSS, as well as for automating some other tasks.

Note: All the gulp <task> commands below should be run from the same directory where gulpfile.js resides.


To generate the HTML pages from the source templates in src/pages/, run:

$ gulp pages

We use the Nunjucks templating engine. The above command will take all the *.njk templates from src/pages/, generate HTML pages, run them through gulp-prettify for pretty output, and save them in the public/ directory.


To generate the CSS from source Sass files in src/sass, run:

$ gulp sass

The above will create style.css in public/assets/css/ directory. It will also create a maps directory in there that will contains the sourcemap for easier debugging in browser's developer tools.

To generate CSS without sourcemaps, run:

$ gulp sassSolo

And finally, the following command should be run before committing CSS changes to Git:

$ gulp autoprefixer

This will generate style.css without sourcemaps, and then use Autoprefixer to add vendor prefixes to CSS rules.

Images, fonts, and JS

The following three tasks are related to images, fonts, and JS, respectively:

$ gulp img
$ gulp fonts
$ gulp js

All of them simply copy the contents of src/assets/img/, src/assets/fonts/, and src/assets/js/ to respective directories in public.

SVG icons sprite

The src/assets/icons/ directory contains all the icons in SVG format. Each SVG file contains a single icon. In order to generate a single SVG sprite that contains all the icons, run:

$ gulp icons

This will generate the SVG sprite (using gulp-svg-sprite) in src/assets/img/ directory. It will be copied to the public/assets/img directory via the img gulp task.

Development flow

The usual development flow starts by running:

$ gulp serve

This starts a local web server, reachable at http://localhost:<port>, and serves the public/ directory.

It also starts watching the following files for any changes and then runs the respective gulp task on every change:

Files watched gulp task
src/scss/**/*.scss sass
src/pages/**/*.njk pages
src/assets/fonts/**/* fonts
src/assets/icons/**/* icons
src/assets/img/**/* img
src/assets/js/**/* js

Thus, we work on our source Nunjucks or Sass files; upon saving, the respective gulp tasks generate the output; and we refresh the browser to see the results.

In order to avoid manually refreshing the browser, use autoserve:

$ gulp autoserve

This is the same as serve, except the browser is also refreshed automatically with each change.

Say Hi

If you'd like to work together on your new game-changer, get a fresh broader look on things, or simply book me for a project, just drop me a line.

Reach me via

© Copyright Usman Nasir. All rights reserved.