How to write a gobblefile

To use Gobble, you have to create a build definition file called gobblefile.js. This is similar to a Gruntfile.js or a Brocfile.js or a gulpfile.js (or, if you're old-school, a Makefile).

Your gobblefile is a recipe for turning your ingredients (source files) into a delicious meal.

For this short document, we'll be referring to this example project. Follow the instructions on that page to clone the example, then delete (or rename) gobblefile.js - we'll be recreating it in this tutorial.

Installing Gobble

In order to use Gobble, you should have it installed in your system. The preferred way is to use NPM for this. You'll need to install the gobble package, and then the gobble-cli package if you want to run gobble from the command-line (or from a shell script):

npm install --save-dev gobble
npm install --save-dev gobble-cli

You can then run Gobble with:

node_modules/.bin/gobble

This is a bit cumbersome, so in most instances it's more comfortable to install gobble-cli globally:

npm install -g gobble-cli

Some terminology, before we start

When you create a build definition, what you're really creating is a dependency graph, where all the nodes are directories of files on disk.

There are three types of node:

• source nodes, which represent the contents of an input folder (and monitor it for changes, if you're serving the project rather than just building it once)
• transformer nodes, which take an input node (of any type) and write files to an output directory
• merger nodes, which merge the contents of several input nodes

Folder structure

Our example project looks like this:

example
|--node_modules
|--src
   |--js    # our JavaScript, which uses ES6 syntax and must be transpiled
      |--app.js
   |--root  # files that we just need to copy across
      |--gobble.mp3
      |--handturkey.png
      |--index.html
   |--styles  # styles to compile to CSS. main.scss imports other files
      |--animation.scss
      |--layout.scss
      |--main.scss
      |--mixins.scss
      |--typography.scss
|--gobblefile.js   # this is where your build definition file goes
|--package.json
|--README.md

Our task is to turn the contents of the src folder into an output folder that's ready for deployment - that means compiling our styles to CSS, transpiling our JavaScript from ES6 to ES5, and copying the static HTML, image and audio files.

Copying files

First, we need to create a source node with the contents of src/root. Write a file named gobblefile.js with the following:

// gobblefile.js
var gobble = require( 'gobble' );
module.exports = gobble( 'src/root' );

If you run the gobble command in your terminal (you must have gobble-cli installed), the contents of that folder will be served to localhost:4567.

Gobble is just taking the files from src/root and exposing them in localhost:4567, like:

In a browser, you should see some unstyled markup - if you check your browser's console, you'll see that it has tried and failed to load main.css. Let's fix that.

Transforming files

We need to take the contents of src/styles, which are Sass stylesheets, and generate a main.css file in plain CSS.

To do this, create a transformer node (we're going to get rid of src/root for this step - it'll come back in a moment):

// gobblefile.js
var gobble = require( 'gobble' );

module.exports = gobble( 'src/styles' ).transform( 'sass', {
  src: 'main.scss',
  dest: 'main.css'
});

Here, we're exporting a transformer node whose input is the source node (src/styles). Notice that you create dependency graphs by simply chaining nodes together with .transform() (and other methods, which you can learn about on the API reference page).

The heavy lifting is going to be done by gobble-sass. You don't even need to npm install --save-dev gobble-sass, as Gobble will help you do that:

Try running gobble now - in your browser, you'll see a directory view with a lone main.css file - that's the result of the transform node.

Any time you change the .scss files, the source node will tell the transformer node that it needs to run again.

Merging files

Great, so we're compiling SASS to CSS, and serving it live to a browser. But that's not much use by itself. We need to combine the output of the first step (creating a source node from src/root) and the second step (generating main.css).

We use the gobble() function again, but this time we use an array instead of a string:

// gobblefile.js
var gobble = require( 'gobble' );

module.exports = gobble([
  gobble( 'src/root' ),
  gobble( 'src/styles' ).transform( 'sass', {
    src: 'main.scss',
    dest: 'main.css'
  })
]);

The merge node will join the files from the previous nodes, like so:

Run gobble now (if you're not already running it, that is - Gobble will monitor your gobblefile, and restart the build automatically when it changes). In your browser, you should see the styles being applied, as Gobble is handling the index.html and the stylesheets.

A second transform

Our src/js folder contains some JavaScript that makes the turkey logo interactive. It uses arrow functions, which are a really convenient syntax for declaring anonymous functions. A lot of browsers don't support them yet (they're a feature of ES6, the next version of JavaScript), so we need to 'transpile' our code to ES5 before serving it to a browser. There are a few different transpilers; we'll be using es6-transpiler with gobble-es6-transpiler:

var transpiled = gobble( 'src/js' ).transform( 'es6-transpiler' );

Of course, we want our Gobble workflow to serve the static files, the CSS stylesheets and the transpiled Javascript together, so we'll merge the three:

// gobblefile.js
var gobble = require( 'gobble' );
module.exports = gobble([
  gobble( 'src/root' ),
  gobble( 'src/styles' ).transform( 'sass', {
    src: 'main.scss',
    dest: 'main.css'
  }),
  gobble( 'src/js' ).transform( 'es6-transpiler' )
]);

Now the SCSS files are transformed in a specific way, the Javascript files in another way, and the static files just copied:

In your browser, click on the turkey. It should gobble!

Cleaner gobblefiles

If your gobblefile looks crowded, you can assign nodes into variables, which probably will make things easier to understand:

// gobblefile.js
var gobble = require( 'gobble' );

var statics = gobble( 'src/root' );

var stylesheets = gobble( 'src/styles' ).transform( 'sass', {
    src: 'main.scss',
    dest: 'main.css'
  });

var javascripts = gobble( 'src/js' ).transform( 'es6-transpiler' )

module.exports = gobble([ statics, stylesheets, javascripts ]);

Static builds

By default, Gobble will watch for changes in the files from the source nodes, run the transformations, and serve the resulting node at http://localhost:4567. In order to make a static build, run gobble build [destination] instead, like:

gobble build dist/

This way, gobble will not watch for changes in the source files, run the transforms just once, and write the result to dist/:

It's also a good idea to use NPM scripts in your package.json file to run gobble whenever you need a static build.

Further reading

Check the documentation for gobble-cli.

Search for gobble plugins in the NPM registry.

No gobble plugin for exactly what you need to do? Then learn how to make gobble plugins