The Asset pipeline

Asset pipeline

Crails comes with an asset pipeline that takes care of many tasks for you. The asset pipeline is based on guard. It watches your file for changes and run the necessary tasks to compile your code or your assets.

Guard has plenty of plugins that you can use on your own, and Crails comes bundled with a few of these plugins, along with some plugins of its own.

The Guardfile

At the root of your project, the Guardfile describes the task that guard needs to take care of, and the files that are to be watched so those task can launch on their own when needed. The tasks are divided in four groups:

• group assets group, takes care of your javascript, stylesheets, images;
• group before_compile group is used by the Crails modules which need to generate C++ code;
• group compile, uses CMake to compile your server;
• group tests, should run your test suites (by default, it runs your server tests, using crails-test).

Launching Guard

Unlike regular guard clients, to use Guard with crails, you need to use the crails guard command. Guard will open and give you a prompt. The tasks will run on their own when needed, but you may also trigger any single task or any group of task by typing its name.

Executing a single group of plugins

You may also run the tasks from a group from the command line, using the crails compile command. For instance, to compile your assets, you would do crails compile assets.

You may also run each task individually: crails compile sass would only compile your stylesheets. Note that crails compile is a shortcut for the compile group (which means running crails compile is the same as running crails compile compile).

The plugins

CrailsJS

CrailsJS is a javascript compiling and minimizing tool that we've developed to take care of the needs of everyone. By default, it concatenates your javascript files together and outputs the result to your public directory.

If you include the coffeescript or typescript-node gems in your Gemfile, CrailsJS will also compile them to javascript for you, before concatenating them with the rest of the files.

Configuring the guard plugin

The options for the plugin are as following:

• input: the root directory for your javascript files. Initially, it is set to app/assets/javascripts
• output: the directory in which your targets are going to be built. Initially, it is set to public/assets
• uglifier: contains the options for the uglifier gem (only relevant in production mode).
• targets: define the targets to compile (for instance, application.js)

Require

As you can see from the configuration, each build target is only a single file. That's because CrailsJs uses comments inside your javascript source to properly concatenate your files. CrailsJs' require system behaves very much like the one from sprockets. Anywhere in your code, you can write //= require other-file.js to make sure that a given file has been included in the target javascript file.

Another helper, //= require_tree folder allows you to require all the files from a folder at once.

• Note that it also works with CoffeeScript, by using #= require other-file.coffee instead.
• Note that files will only be required once. If you wish to include them several times, use //= include file.js instead.

Multi-language

You should be able to mix Javascript and CoffeeScript, or Javascript and TypeScript. Supposedly, you should also be able to mix CoffeeScript with TypeScript, but this isn't recommended.

SASS

By default, your Guardfile also comes with the sass guard plugin. You can check out its documentation on its github repository.

CrailsCMake

CrailsCMake watches your project source and re-compile it everytime there's a change.

On larger project, this may become a hindrance. You can disable the re-compiling by commenting the associated watchers that are defined by default on your Guardfile. You may then still compile your project from guard by typing crailscmake from the prompt.