roto

    0.3.6 • Public • Published

    roto

    A no-nonsense build tool for Node.js projects.

    Roto is designed to be a lean build tool. Build targets are defined as functions. Inside of which, simply add tasks that are executed sequentally. Roto is in its very early stages—use it with some caution.

    To install: npm install -g roto

    Bundled Tasks

    A few common, useful tasks come built-in to roto.

    • s3 — Syncs a local folder to S3.
    • concat — Concatenates two or more files.
    • handlebars — Precompiles Handlebars templates to JS.
    • lint — Validates Javascript source code (using jshint).
    • uglify — Minifies Javascript source code (using uglifyjs).
    • mocha — Performs unit tests (using mocha).
    • less — Precompiles LESS stylesheets to raw CSS.
    • png — A suite of various PNG optimization tools (pngcrush, pngquant, and optipng).
    • dir-copy — Copies a directory and its contents.
    • dir-move — Moves a directory and its contents.
    • dir-remove — Deletes a directory and its contents.
    • template — Generates a file from a template.

    Setting up a Project

    Create a build.js file in your project root. This is where you'll define all your build targets and set up the tasks that make up those targets. Here's the basic idea:

    module.exports = function(roto) {
        roto.addTarget('www', function(options) {
            // minify js files
            roto.addTask('uglify', {
                files  : ['js/*.js'],
                ignore : ['js/*.min.js'],
                output : 'js/combined.min.js'
            });
     
            // do something custom
            roto.addTask(function(callback) {
                console.log('This isn\'t using a predefined task. Saweet.');
                callback();
            });
        });
    };

    To set the default target that is used (should one not be given at build time), set roto.defaultTarget. If left unchanged, all targets are built.

    roto.defaultTarget = 'target-name';

    Adding Predefined Tasks

    To invoke a predefined task as part of your build process, use roto.addTask(name, options)—where name is the name of the predefined task. For options, consult the documentation for that task (located here).

    roto.addTask('uglify', {
        files  : ['js/*.js'],
        ignore : ['js/*.min.js'],
        output : 'js/combined.min.js'
    });

    In more complicated builds, task options might need to be computed at execution time. This can be done by providing a function instead of an object:

    roto.addTask('uglify', function() {
        return {
            files  : ['js/*.js'],
            ignore : ['js/*.min.js'],
            output : 'js/combined.min.js'
        }
    });

    Adding Custom Tasks

    If there's something specific you need to do that doesn't have to do with a predefined task, simply use roto.addTask(callback):

    roto.addTask(function(callback) {
        // logic goes here
        callback();
    });

    Executing Other Targets

    In some cases, executing another target from the current target makes sense (e.g. a "deploy" target needing to run the "clientside-build" target first). To do this, use the following syntax:

    roto.addTask('target:clientside-build', options);

    Invoking Tasks Within Other Tasks

    Predefined tasks can be manually invoked using the "executeTask" method, like so:

    roto.addTask(function(callback) {
        roto.executeTask('uglify', options, callback);
    });

    Odds & Ends

    Colorizing Strings

    A utility for colorizing strings comes bundled with roto.

    var colorize = roto.colorize;
     
    console.error(colorize('ERROR:', 'red') + ' Something borked.');
    console.log(colorize('SUCCESS:', 'green') + ' Something went right!');

    The available colors are currently: red, yellow, green, and white (bold).

    Defining Reusable Tasks

    For defining custom tasks that can be reused (like the predefined ones that come bundled with roto), use:

    roto.defineTask(name, function(callback, options, target, globalOptions) {
        // logic goes here
        callback();
    });

    The arguments provided to the callback are:

    • callback – Invoke to move on to the next task. This is crucial (otherwise your build will hang).
    • options — User-provided options that are given when calling roto.addTask.
    • target — Information about the target currently being executed { name: 'target-name', tasks: [...] }.
    • globalOptions — Options provided at the command line, or when calling roto.run.

    Executing a Build

    From Javascript

    var roto = require('roto');
    require('./build.js')(roto);
     
    // build a single target
    roto.run('target-name', {}, function(success) {
        console.log('Build complete!');
    });
     
    // build a few targets
    roto.run(['target-name', 'whatevs'], {}, function(success) {
        console.log('Build complete!');
    });

    Command Line

    roto target [options]
    

    Options

    Options can be provided in a variety of ways:

    roto target debug --message=hello -x 1 -y 2
    

    This leads to options being:

    {
        debug: true,
        message: 'hello',
        x: 1,
        y: 2
    }

    Keywords

    none

    Install

    npm i roto

    DownloadsWeekly Downloads

    2

    Version

    0.3.6

    License

    none

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar