Matt Lambert

Check out my blog, or sign up to receive articles by email.

How to use the Harp.js static site generator

By admin on October 13th, 2015 in Development

If you’ve ever worked on a large website, you can understand the pain of changes to navigation or other global elements. In the past it often required the manual update of large amounts of HTML pages. Definitely one of the less glamorous aspects of web design. Enter static site generators that allow the designer to code up their website using a template based system. If you’ve ever used WordPress this is similar to creating a theme. You isolate your global elements into includes and templates, then load in the content for each page separately. This allows you to more easily maintain your websites and make your life much simpler.

Harp.js – the static web server with built-in preprocessing

My tool of choice for static site development is Harp.js. The tool allows you to code your HTML in a number of templates like EJS, Markdown and Jade. You can use CSS pre-processors like Less, Sass and Stylus. As well as JavaScript pre-processors like CoffeeScript. When you compile your project with Harp it will convert your template code into vanilla HTML, CSS and JavaScript. The outputted files can then be deployed to your server. Another bonus of Harp is that it is built on Node.js so there is a built in web server that you can use to preview your project locally before you push it to production.

Installing Harp

Let’s go over the basic of installing Harp on your local machine. If you run into problems, take a look at their docs website. I’m going to assume you’re on a Mac. If you’re using windows consult the docs for the proper commands. If you haven’t already go to nodejs.org and install Node. Once you’ve done that, open up the Terminal app on your Mac and run the following command to install Harp.

$ sudo npm install -g harp

That’s it, you will see some action in the terminal and if there are no errors you are good to go. Run the following command to ensure it worked:

$ harp -V

Now that Harp is successfully installed let’s setup a basic project.

Setting up a basic project

On your computer head to the directory where you save all your websites. If you want to use Jade templates, navigate to this folder in the Terminal and run the following command. Replace myproject with the name of your project.

$ harp init myproject

This will build a basic project that you can start using right away. My problem is I prefer to use EJS templates because they more closely resemble HTML and the learning curve isn’t that steep. Let’s create a second project and assemble it ourselves. Create a second directory where you save your websites. Within your project, create the following directories:

/css
/img
/js
/partial

We also need to create a few files in the root of the project. Create the following files and just leave them blank for now:

_data.json
_harp.json
_layout.ejs
_index.ejs

Let’s also create some container files for the header and footer of our project. Open up the partial directory and insert the following two files:

_header.ejs
_footer.ejs

Setting up the asset files

The next thing we need to do is setup our CSS and JavaScript files. Open up the css directory and insert a blank file called theme.less. I’ve decided to use Less for this example. Now open up the js directory and create a file named project.js. If you don’t like these names, feel free to name them whatever you want.

theme.less is going to hold all of the CSS/Less code for your project. You can also insert other Less or CSS files here like Bootstrap then insert them into your layout. project.js will be for any project specific JavaScript you might want to include. This file is totally optional but you will likely have some scripts for your project. Like the CSS directory you can include additional JavaScript libraries here that can be inserted in your layout template.

Setting up the json files

Earlier we created two json files in the root of our project: _harp.json and _data.json. The first file is for defining things like global variables that will apply to all pages in our project. Let’s setup a variable for the name of our project which we’ll insert into the <title> tag of our template.

{
    "globals": {
        "siteTitle": "Logic Designer"
    }
}

The second file we need to setup is _data.json. This file is for setting up things like variables on the page level. Let’s go ahead and setup a page title variable that we would need to set for each page of our project. We’ll also insert this into the <title> tag of our layout template.

{
    "index": {
        "pageTitle": "Home"
    }
}

Save both of the files and then we’ll start setting up our actual page templates.

Setting up the layout

Each page in the project is made up of two files. _layout.ejs is the master page template that wraps the content of the page. The actual page content is contained within a different .ejs file for each page. In this case we only have index.ejs to worry about. Open up a _layout.ejs and insert the following code.

Let’s go over a few parts of these template:

  • I’ve inserted the variables for siteName and pageTitle into the <title> tag of the template.
  • I’ve loaded theme.css in the <head> of the template. Remember to change the extension to .css as this conversion will happen when we compile the project.
  • In the body you’ll notice we’re inserting our header and footer partials. The code for those sections will be inserted there for each page. Now when you edit your header links you only have to do it on one place!
  • The <%- yield %> tag marks where our content will be loaded. So index.ejs will be loaded into where this tag appears.
  • At the bottom I’ve included jQuery and our project.js file. jQuery is optional.

That’s it, the layout is now ready to roll. The last thing we need to do is setup our index file. Open up the index.ejs file and insert some regular HTML code for the content of your page. Once you’re done that save everything and we’re ready to compile our project for the first time.

If you’d like to use a Boilerplate for the project that includes Bootstrap, check out a project I created over at Github: github.com/cardeo/booterator.

Compiling your project

When you compile your project in Harp it will convert all of your template and Less files into vanilla CSS files. It won’t touch any files that are already using the .css or .js extensions. Navigate to the root of your project in the Terminal and run the following command:

$ harp compile

If you receive no errors you’re project is ready for preview! Go back to the root directory and you’ll notice there is a new www directory. You’re compiled files are included in this directory. When you are ready to deploy you can copy this folder to your web server.

Previewing Your Project

Before you deploy though let’s test out our project with the built in Node web server. From the root of your project, enter the following command into the Terminal to start the server:

$ harp server --port 9000

Now open up a web browser and insert the following URL:

http://localhost:9000

Your website should load up and you can preview everything before you decide to push it to production. To close the web server down, hit ctrl+c. Once you’re ready to deploy, you can copy your files in the www directory to your web server. If you don’t have a web server, you could use Surge to deploy your project for free.

Deploying your project with Surge

Surge was created by the same team that built Harp so they work really well together. The first thing you need to do is install Surge by running this command in your Terminal:

$ npm install --global surge

Once Surge is installed run the following command from the root of your project in the Terminal:

$ surge

A sub-domain will be generated for you automatically and shown in the Terminal. You do have the option of customizing the domain if you like. Once you accept the domain the project will be deployed to the Surge servers. On completion, visit the sub-domain in a web browser and you can see your project live on the internet. Surge is a free service but they do have a premium version that will unlock other features like the ability to use your own domain name.

In less than an hour you can setup a front end development environment for your static website projects using Harp and Surge. I hope you see the awesome benefits of these tools and will start to use them for all your static website projects.

Like what you read? Check out my store over at Creative Market to support the blog and help keep the lights on. Files starting from only $2.
  • Sepol Luap

    Would you say harp is better than hugo? or are they diff things?

    • Hi Sepol, I hadn’t actually heard of Hugo until you mentioned it. I checked it out and it looks pretty cool. It’s definitely similar to Harp and you could use either as a static site generator. I think I’ll likely give Hugo a test drive at some point, thanks for mentioning it as it looks pretty cool

  • Ernest Mistiaen

    Thanks for pointing me to Harp, Matt! I stumbled upon your ‘How I almost shipped a product every month in 2015’ (which was very inspiring by the way) and checked out Harp. I’ve been playing with it during the holidays and today I started my first serious Harp project. Liking it a lot.

    • Hi Ernest, thanks for reading my posts and taking the time to comment! Glad you are finding Harp useful, it’s probably my current favourite tool to use. If you run into any questions, feel free to post them here.