Getting Started with Foundation 6’s CLI Tools

The recently released Foundation 6 gives you many ways and tools to use it. You can download the static files, or you can use Yeti Launch, a special desktop app for Mac (soon there will be a Windows version).

A lesser-known feature is a set of command line tools available with Foundation 6, and that’s what I will cover in this article. Foundation 6 is a really flexible front-end framework, which, besides many obvious CSS features and JavaScript plugins, also has great developer tools.

When Might I Want to Use Foundation’s CLI Tools?

You’re probably asking why you should bother with CLI tools when you have access to the static JavaScript and CSS files, which works just fine. You probably need standard structures and an easy-to-use workflow, and that’s ok.

I’m sure you can achieve your goals that way, but I know that there are many developers who want to gain more control over the build process. This would include SCSS compilation, concatenation, minification, image optimization, and templates. I prefer to have access to these extra tools. And so there are use cases where CLI tools might be a better option.

If you work regularly with the command line but don’t know exactly what Foundation 6 has to offer in this area, or you don’t work with the command line and maybe want to learn something new, then this article is for you.

Up and Running

To get started there are some prerequisites. You’ll need to have NodeJS installed and also the npm tool that should be installed with NodeJS. You also need Git, Gulp, and Bower, all of which our foundation-cli will use. You can install these by running the following command:

$ npm install --global gulp bower

On some systems you’ll need super user access, especially when installing something with npm globally, so you might need to use sudo before the commands described in this post.

Installing foundation-cli

If you already have the Foundation 5 CLI on your machine, you’ll only be able to access one of the commands, depending on how your command line environment is configured. So it’s better to remove the old tools first. You can do this with the following commands:

$ gem uninstall foundation
$ npm uninstall --global foundation-cli

Then install the new CLI tools:

$ npm install --global foundation-cli

You can read more about the installation in Foundation’s documentation.

If you don’t want to install foundation-cli on your system and you have installed Gulp and Bower in the past, you can simply clone the repository with the Foundation template and then instead of using the foundation command, you can use the gulp and npm commands. Everything should work the same way as when using foundation-cli.

What Does Foundation CLI Give Me?

As mentioned, Foundation CLI uses Gulp and Bower under the hood. What are Gulp and Bower? Gulp is a toolkit that will help you automate painful or time-consuming tasks in your development workflow. Here, we can think of SCSS compilation, minification, concatenation, but also image compression or other useful tasks. Bower is a package manager for the web, which lets you download and install front-end libraries via the command line. For example, installing jQuery is a one line command: bower install jquery.

Foundation CLI downloads and installs blank templates for any of the three Foundation frameworks: Sites, Apps, and Emails. All of these templates are ready to work with Gulp and Bower, with preconfigured Gulp tasks and Bower installation sources. This is similar to a tool like Yeoman.

Using Foundation CLI

When you’ve installed foundation-cli, you can start using it by running:

$ foundation new --framework sites --template zurb

As you can see, we use foundation as the name and not foundation-cli. Also, we’ll only take a look at the Foundation for Sites zurb advanced template. We need to use the --framework flag to choose the proper framework and also the --template flag to choose the proper template. You can also choose the basic template, but I think the advanced is much better if you want to take a closer look.

After the installation, you should have a project folder with the name you’ve provided during the installation. Also, all dependencies should be installed there. All you need to do now is cd into the newly created project and inside the folder you can run:

$ foundation watch

Here comes the magic! What this does is run the Gulp build and server tasks and also the watch command. This means it triggers all configured Gulp tasks, which you will be able to see in the code. So when you run this command you should see some information in the console. The most important for now are:

------------------------------------
  Local: http://localhost:8000
  External: [... your external IP here ...]
-----------------------------------------------
  UI: http://localhost:3001
  UI External: [... your external IP here ...]
-----------------------------------------------
 [BS] Serving files from: dist

Here you have information about your running servers. The first is your actual application, and you also have a UI server for BrowserSync testing (we’ll talk about that shortly). You can see that your app files are served from the dist directory and you can visit http://localhost:8000 in your browser and see the standard Foundation 6 starter template.

Taking a Look at What’s Inside

I think this is the most exciting part, but we had to go through all the installation process before getting to this point.

Folder structure, Gulpfile.js, JavaScript/CSS Assets

Let’s take a look at the folder structure of the newly created project. The most important folders are src and dist. Your development work will be done mostly in the src folder and all your production files will be prepared in the dist folder. The server that you run serves files from that folder as well. This means that you can prepare your workspace as you want, but in the end, production ready files will land in the dist folder and this is what you want to serve as your finished product.

So, how is this possible? Let’s take a look at our most important file here – gulpfile.js. If you aren’t familiar with Gulp, you might want to check out this introductory tutorial. Gulp isn’t as scary as it looks in the beginning, but it’s important because this is the place where all the magic happens.

Gulp is based on many Gulp plugins that add additional functionality via simple npm packages. In this new Foundation project they are defined in package.json. They are also downloaded and installed automatically when running foundation new (as above), so you don’t need to worry about that.

When you open the Gulp file, you can see that every task such as clean, copy, sass, and JavaScript is defined similarly using the special Gulp plugin that is responsible for this particular part of the job. Additionally, as you can see at the bottom of the file, there are main tasks like ‘build’ or ‘default’ which aggregate others. Foundation boilerplate is configured, so you basically don’t need to do anything. Of course you can adjust it as you’d like.

With this kind of config, you can write your scss in the src/assets/scss folder, and you can write your JavaScript files in the src/assets/js folder. You can also place your images in the src/assets/img folder. When you run foundation watch or foundation build, all those files will be copied to the dist folder. Depending on the options, they can be compressed or images can be optimized. This is all configured in the gulpfile.js.

Gulp configuration and its plugins are a topic for another article. Let’s now take a look at the .html files and create advanced layouts and relations with Panini.

Panini and Handlebars Templates

Panini is an awesome and simple tool built by the Foundation team. With Panini, you can create pages with consistent layouts and reusable partials.

In your dist folder, you have ready-to-use static HTML files. Of course, if you have just one file, everything is really simple. Problems might occur when you want to create many HTML files that have a couple of identical parts. It could be a footer, sidebar, header or many other elements that are called partials.

Without Panini, you would need to copy all that repeating code into each HTML file, and if a change is needed you’d have to either do it manually in each file, or do a find-and-replace in your text editor. With Panini, you can do this all in one place while editing and all files will be edited and copied into the dist folder.

What is also important is that Panini is a built on the Handlebars templating library. It can compile Markdown in your HTML files as well. More info on Panini can be found in Foundation’s docs.

Let’s take a look at the Panini templates folder structure in the project. We need to open the src folder. Here we have data, layouts, pages, and partials. As you can expect, in the layouts folder, we can write our main layout scaffolds. Here we can define a header and footer that will be repeated on all pages.

If you want to use only one layout, you can just name the file default.html. You will find a demo file like that in our project. If you want to use more than one layout, you can create more files with special body tags {{> body}} (see the default.html example) and you will need to use special markers in your pages to tell the compiler which layout a page should use. It is called Front Matter and looks like:

---
layout: my-custom-layout
---

These markers should be placed at the top of a page file content. This is only for pages that will use this layout, all others will use the default one.

Let’s take a look at the pages folder. In this folder, you’ll find the index.html file, which is a content demo page. As you can see, it doesn’t have any html or body tag. This is because it is just the content that will be injected into the previously discussed default.html layout.
You can of course add similar pages, but some might use different layouts.

If you want some small, reusable HTML elements, you can create them in the partials folder. There aren’t any files in the demo project which we have created, but this is really simple. Just create a file with a fragment of HTML and name this file whatever you want. Then in your layout files or pages files, you can import this partial by including it using something like: {{> my-partial-file}} (notice there is no file extension). And that’s it. All will be connected, compiled, and copied into the dist folder.

There is also a folder called data. Here you can provide some data in the format of .json or .yml files. So for example, let’s say I have a myList.json file in the data folder with the following content:

{
  items: ["item 1", "item 2", "item 3"]
}

In the layout page or partial HTML files, I can use something like:

<ul>
  {{#each myList.items}}
    <li class="item-name">{{this}}</li>
  {{/each}}
</ul>

This lets you iterate through the JSON data and produce some HTML. What we should get is a list of items with the names from the array.

As you can see, Panini is a really useful tool when you want to create complicated HTML structures and you don’t want to repeat yourself.

BrowserSync: Synchronised Browser Testing and Live Reload

The last preconfigured feature of the Foundation CLI tool I’m discussing is BrowserSync. As you probably know, front-end work is hard because you need to test your website on many devices and many resolutions. Now imagine that you have a big table with many different devices connected to your website. When you click something or scroll the page, all devices will do the same. This is great because you see in real time what should be corrected and what doesn’t work well.

Our created project automatically provides your external IP address (see above). You can take it and paste it in all different device browsers to connect to the same BrowserSync engine and start testing.

BrowserSync also provides live changes so, if you save something, it will appear in the browser window without manually refreshing the page. It will also appear on all connected devices and you get this all for free with the foundation-cli and zurb templates without any additional work. How awesome is that?

Final Words

I personally think that the Zurb Foundation team has done a very good job providing great tools and scaffolds for developers. This is what matters too. Not only some ready-to-use plugins and CSS styles. Working with Foundation for Sites 6 is a great experience. Just imagine how much work you can do with the Foundation CLI tools without programming the backend. You can create static websites and blogs and they could be quite advanced too. Not to mention that in many cases, static blogs and websites are even faster and better.

I really encourage you to take a better look at Panini. You can also find some documentation on the npm package readme. It can do many awesome things that I haven’t described here, like Markdown compilation or custom helpers. You can read about Gulp and take a closer look at all Gulp tasks used in the zurb template/project generated by the foundation-cli tool as well.

One more thing – I didn’t mention compressed CSS and JavaScript files. If you’re using the foundation watch command, you’ll have CSS and JavaScript files in the dist folder but they will be uncompressed. If you want production-ready files in that folder, just run foundation build. If you want to read more about the foundation command, just run the foundation help command. When the time comes and you need to update your dependencies in the project, you can run foundation update.

So all in all, I hope that you’ve learned something here. If you have questions, let me know in the comments or check out my profile for different ways to get in touch with me.