Skip to main content

Building your static site with Hugo, FlightJS, SASS and Gulp

Hugo provides a good workspace for creating layouts and content. I'm very much satisfied with the options available to customise the site. However, Hugo does not have a say in how CSS and JavaScript should be structured so that it can be included on our site. In Hugo, the DOM nodes are already created and we need a mechanism which we can employ in adding event listeners to these DOM nodes.

SPA frameworks like Angular and React, create DOM nodes and define event listeners in the controller of the component. To attach event listeners to an existing DOM tree I came across a JavaScript framework called FlightJS. It's a framework created by folks at Twitter that helps in adding behaviour to the DOM nodes. It's a minimal framework which does not dictate how the DOM nodes should be rendered nor it dictates the other aspects of the web application, such as routing, request/response handling, structuring data so that other components can consume it etc. FlightJS provides only a mechanism that enables us to add behaviour to the existing DOM nodes.

This is exactly what I needed to build my static site. Let's take a look at how I have structured my site using SCSS, FlightJS and Gulp for building the static content:

--src
  --js
    --pages
      --home
        --index.js
    --vendor
      --flight.js
      --jquery.js
  --styles
    --pages
      --home
        --index.scss
      --vendor
        --index.scss

I have created an 'src' directory in my Hugo site which will contain all the JavaScript and SCSS files. Hugo's documentation suggests that we need to keep all static content (JavaScript, CSS, images, font files etc) in 'static' directory. Here 'src' directory will contain the development code i.e. unprocessed SCSS files and non-minified JavaScript files. The 'static' directory, on the other hand, will contain CSS code (processed SCSS) and minified JavaScript files which are production ready.

In our example, the FlightJS code can be included in 'js/pages/home/index.js' file. Here's the code which creates a FlightJS component, defines a 'click' event handler and attaches the component to an existing DOM node:


FlightJS has a dependency on jQuery and thus you see jquery.js present in the 'vendor' directory. A lot can be done with FlightJS, however, I'm restricting this post to build a proof of concept which demonstrates the minimal functionality.

The next step is to add a build process that compiles the SCSS files, compress and concatenates JS files and creates a hash for these files for browser cache busting. I'm using GulpJS to create a pipeline build and here's the sequence:

  1. Compile SCSS files - compile 'pages' and 'vendor' files separately.
  2. Concatenate the vendor related CSS files.
  3. Move the generated files to 'static/css' directory.
  4. Compress the JS files - 'pages' and 'vendor' files separately.
  5. Move the generated files to 'static/js' directory.
  6. Use 'gulp-hash' to create a hash for the generated JS and CSS files. Create a hash manifest file and place it in the 'data' directory (assets_js.json and assets_css.json).

The gulpfile.js used to build the pipeline can be referred here: https://github.com/sagar-ganatra/hugo_example/blob/master/gulpfile.js

After compiling and generating content in the 'static' directory, you can refer to these files in your layout templates:

<link href="{{ .Site.BaseURL }}css/vendor/vendor.css }}" rel="stylesheet" type="text/css">
<script src="{{ .Site.BaseURL }}js/vendor/vendor.js }}"></script>

Here the template variable {{ .Site.BaseURL }} would be replaced with the baseUrl defined in the config.toml file and when the generator creates the static files, it would be referring to the file '<site>/css/vendor/vendor.css' and '<site>/js/vendor/vendor.js'. Since we are creating adding a hash to these files, it would not be possible to refer to 'vendor.js' and 'vendor.css' files like this. However, we can use the manifest files created when generating a hash for referring these files.

As noted in the last step of the Gulp build process, we are creating manifest files 'assets_js.json' and 'assets_css.json' in the 'data' directory. The content is a JSON structure that contains hash references:

{
  "pages/home.js":"pages/home_4740e2cf.js",
  "pages/home_debug.js":"pages/home_debug_3f723556.js",
  "vendor/vendor.js":"vendor/vendor_f8da36b2.js",
  "vendor/vendor_debug.js":"vendor/vendor_debug_b3868b34.js"
}

Hugo can read files in the 'data' directory and it supports TOML, YAML and JSON file formats. Now we can modify our template to get the hash refernce from the asset files:

<link
    href="{{ .Site.BaseURL }}css/{{ index .Site.Data.code_assets.assets_css "vendor/vendor.css" }}"
    rel="stylesheet"
    type="text/css">

and

<script
    src="{{ .Site.BaseURL }}js/{{ index .Site.Data.code_assets.assets_js "vendor/vendor.js" }}">
</script>

The template variable '.Site.Data.code_assets.assets_js' will contain reference to the values in the file 'data/code_assets/asset_js.json' and the reference key 'vendor/vendor.js' would return the value assigned to it (vendor/vendor_f8da36b2.js).

Code is shared on my github repository here: https://github.com/sagar-ganatra/hugo_example

Comments

Popular posts from this blog

De-obfuscating javascript code in Chrome Developer Tools

I had blogged about JavaScript debugging with Chrome Developer Tools  some time back, wherein I have explained how these developer tools can help in debugging javascript code. Today Google Chrome 12 was released and my Chrome browser was updated to this version. As with every release, there have been some improvements made on performance, usability etc,. One feature that stood out for me is the ability to De-obfuscate the javascript code. What is Minification? Minification is the process of removing unnecessary characters such as white spaces, comments, new lines from the source code. These otherwise would be added to make the code more readable. Minifying the source code helps in reducing the file size and thereby reducing the time taken to download the file. This is the reason why most of the popular javascript libraries such as jQuery are minified. A minified jQuery file is of 31 KB in size where as an uncompressed one is about 229 KB. Unfortunately, debugging minified javascript f

Adding beforeRender and afterRender functions to a Backbone View

I was working on a Backbone application that updated the DOM when a response was received from the server. In a Backbone View, the initialize method would perform some operations and then call the render method to update the view. This worked fine, however there was scenario where in I wanted to perform some tasks before and after rendering the view. This can be considered as firing an event before and after the function had completed its execution. I found a very simple way to do this with Underscore's wrap method.

On GraphQL and building an application using React Apollo

When I visualize building an application, I would think of using React and Redux on the front-end which talks to a set of RESTful services built with Node and Hapi (or Express). However, over a period of time, I've realized that this approach does not scale well when you add new features to the front-end. For example, consider a page that displays user information along with courses that a user has enrolled in. At a later point, you decide to add a section that displays popular book titles that one can view and purchase. If every entity is considered as a microservice then to get data from three different microservices would require three http  requests to be sent by the front-end app. The performance of the app would degrade with the increase in the number of http requests. I read about GraphQL and knew that it is an ideal way of building an app and I need not look forward to anything else. The GraphQL layer can be viewed as a facade which sits on top of your RESTful services o