Creating our first page template

For our first page template, we're going to create our Home or index page. In the root of the blog project, create a new file called index.ejs. Note this file is not prepended with an underscore like the previous files. With Harp, any file that has the underscore will be compiled into another and ignored when the files are copied into the production directory. For example, you don't want the compiler to spit out layout.html because it's fairly useless with the content of the Home page. You only want to get index.html, which you can deploy to your web server. The basic thing you need to remember is to not include an underscore at the beginning of your page template files. Once you've created the file, insert the following code:

<div class="container"> 
  <div class="row"> 
    <div class="col-lg-12"> 
      <h1>hello world!</h1> 
    </div> 
  </div> 
</div> 

To get us started, I'm going to keep this really simple. Here's a quick breakdown of what is happening:

• I've created another .container which will hold the content for the Home page
• Within the container, there is a full-width column. In that column, I've inserted an <h1> with a hello world! message

That will be it for now. Later on, we'll build this page out further. Save the file and close it. We've now completed setting up all the basic files for our Harp development environment. The last step is to compile the project and test it out.

Compiling your project

When we compile a project in Harp, it will find all the different partial, layout, and template files and combine them into regular HTML, CSS, and JavaScript files. We haven't used any Sass yet but, as with the template files, you can have multiple Sass files that are compiled into a single CSS file that can be used on a production web server. To compile your project, navigate to the root of the blog project in the Terminal. Once you are there, run the following command:

$ harp compile

If everything worked, a new blank line in the terminal will appear. This is good! If the compiler spits out an error, read what it has to say and make the appropriate changes to your template files. A couple of common errors that you might run into are the following:

• Syntax errors in _harp.json or _data.json
• Syntax errors for variable or partial names in _layout.ejs
• If you have created additional page templates in the root of your project, and not included them in _data.json, the compile will fail

Once your compile is successful, head back to the root of the blog project and notice that there is a new www directory. This directory holds all the compiled HTML, CSS, and JavaScript files for your project. When you are ready to deploy your project to a production web server, you would copy these files up with FTP or using another means of file transfer. Every time you run the harp compile command in your project, these files will be updated with any new or edited code.

Running your project

Harp has a built-in web server that is backed by Node.js. This means you don't need a web hosting account or web server to actually test your project. With a simple command, you can fire up the built-in server and view your project locally. This is also really great if you are working on a project somewhere with no Internet connection. It will allow you to continue building your projects Internet-free. To run the server, head back to the Terminal and make sure you are still in the root directory of your blog project. From there, enter the following command:

$ harp server

In the Terminal, you should see a message that the server is running. You are now free to visit the project in a browser.

Viewing your project

Now that the project is up and running on the web server, simply navigate to the following URL to view it: http://localhost:9000.

By default, Harp runs on port 9000 but you can specify a different port by modifying the last command. Go back to the terminal and quit the server by hitting Ctrl + C. Now enter the following command:

$ harp server --port 9001

Using this command, you can invoke any port you would like to use. Head back to the web browser again and change the URL slightly to read http://localhost:9001.

Your project should load for you and look something like this:

It might not be much to look at right now but it works! Your project is successfully set up and running. In future chapters, we'll add to this page and build some more using additional Bootstrap 4 components.

A note about Sass

When building a project with Bootstrap 4, there are two ways you can work with Sass. The first would be by editing the actual Bootstrap framework files and then recompiling them using Grunt. This is useful if you'd like to use something such as Flexbox for your grid layout. I'll discuss this in greater depth in the next chapter. The other way you might want to use Sass is to craft a unique theme that applies a custom look and feel to Bootstrap. This is done in the actual Harp project. Within the css directory, you can include Sass files; when you compile your Harp project, they will be converted to regular CSS, as Harp has a built-in Sass compiler. Then it is just a simple exercise of including those additional files in your layout template. I'll also get into that a little later in the book but I wanted to point out the difference now.