Developer docs

Using Gulp in a Ghost theme to compress CSS and JavaScript

In this tutorial we’ll show you how to enhance your theme development with Gulp. By the end of this tutorial you’ll have a better understanding of how Gulp works and how it can dramatically improve your Ghost theme development experience.

Prerequisites

The following steps require experience with using command line interfaces such as Terminal, and CLI tools like npm or yarn. Check out the official npmjs documentation and yarn documentation for more information.

Introduction

JavaScript and CSS are two of the most core languages that make up the web. Ghost themes are built upon these core languages, meaning that any JavaScript or CSS that works on the web can be used in a Ghost theme. Gulp is a tool for enhancing your JavaScript and CSS, such as compiling multiple files together or minifying files for better site performance. We find it very helpful when building Ghost themes.

Getting started

Pro tip: Starting a new theme for Ghost? Check out our starter theme which a clean canvas to begin your new project, and includes the gulp.js configuration explained in the following steps 🧰

Navigate to the root folder of your Ghost theme using your CLI (Command Line Interface). Use npm or yarn to install Gulp:

npm install --save-dev gulp

# For yarn users
yarn add --dev gulp

In this tutorial we’ll be showing a pared down use of Gulp in a Ghost theme, and will only be handling JavaScript. To find out how to handle other assets check out our Starter Ghost theme and the official Gulp documentation, as well as this useful guide on CSS Tricks.

Alongside gulp, install these following development dependencies:

npm install --save-dev gulp-uglify pump

# For yarn
yarn add --dev gulp-uglify pump

Creating a gulpfile

Your gulpfile is where you’ll be telling gulp, along with the other scripts you’ve installed, what to do with your theme asset files. These commands are called “tasks” and are written as JavaScript inside your gulpfile.js file.

Create a new file called gulpfile.js at the root of your theme and open it in a code editor. Use require to import Gulp and all the other dependencies you installed in the previous steps.

const gulp = require('gulp');
const uglify = require('gulp-uglify');
const pump = require('pump');

Creating a task

In a typical Gulp task some files are sourced from a folder, transformed and then sent to a destination folder. In the following example we’re going to source some JavaScript files, minify them using gulp-uglify and then put them into a destination folder called built. Below the import lines add the following Gulp task function:

function js(done) {
    pump([
        gulp.src('assets/js/*.js', {sourcemaps: true}),
        uglify(),
        gulp.dest('assets/built/', {sourcemaps: '.'})
    ], done());
}

You’ll notice that the steps have been wrapped in a function called pump. Pump is “wrapper” tool around pipe, which is a native tool in Gulp. pipe is for sending files through a transforming tool such as uglify shown in the above example. pump wrapped around that method and makes the use of it a bit more straightforward for us. If you want to learn more about pump check out this documentation explainer.

Finally, we need to export this task so it’s available for us to use in the CLI.

exports.js = js;

Using a task

Because we’re using Gulp within our theme project we need to expose Gulp and the tasks we’re creating via the package.json, the file that stores essential information about the project.

Pro tip: Already using Gulp in other projects? You might only be using “gulp” or “gulp dev” in your CLI. You could do that in your Ghost theme too, however we recommend using the following method of running commands. It’s especially helpful when working in teams, so you can be sure you’re all using the exact same version of Gulp ⛑

To expose our gulp js task open the package.json file in a code editor, locate the scripts item and add “js”: “gulp js” like so:

"scripts": {
    "test": "...",
    "js": "gulp js"
},

To test your newly created task return to your CLI and run the following command:

npm run js

# For yarn users
yarn run js

If the task has been successful you’ll see messages similar to this in your CLI:

Example of the logs shown in a CLI after running the gulp js command

You’ll also see an updated “built” folder containing your minified JavaScript.

Example of the files built after running the gulp js command

Woohoo! You’ve just created your first gulp tasks and already well on your way to creating a streamlined and automated Ghost theme development workflow 🎉

Zip up your theme with Gulp

Gulp is a very flexible tool and can be used to transform all sorts of files in your theme. Another way in which we use Gulp is to zip up our themes so they can be uploaded to Ghost admin. Here’s how you could do that with Gulp:

const gulp = require('gulp');
const zip  = require('gulp-zip');

function zipper(done) {
    var targetDir = 'dist/';
    var themeName = require('./package.json').name;
    var filename = themeName + '.zip';

    pump([
        gulp.src([
            '**',
            '!node_modules', '!node_modules/**',
            '!dist', '!dist/**'
        ]),
        zip(filename),
        gulp.dest(targetDir)
    ], done());
}

exports.zip = zipper;

One of the clever parts of this task is that it skips the node_modules folder, which is only needed in the development of a theme and can sometimes make the theme file size very large. After adding the task to the package.json file (“zip”: “gulp zip”) you could run the following command to zip your theme up:

npm run zip

# For yarn users
yarn run zip

This would take the essential theme files and zip them up into a file named the same as the theme and place it into a folder called dist.

Summary

While using Gulp may be considered a more advanced form of web development tooling, Ghost themes still base themselves on core web frameworks such as HTML, CSS and JavaScript. These coupled with Handlebars to provide the theme data layer are a strong combination. Check out our official Handlebars documentation to learn more about making Ghost themes.