Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A simple build tool for html/js/css projects.
JavaScript HTML

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


buddy(1) is a build tool for js/css projects. It helps you manage third-party dependencies, compiles source code from higher order js/css languages (CoffeeScript/Stylus/Less), automatically wraps js files in module definitions, statically resolves module dependencies, and concatenates (and optionally compresses) all souces into a single file for more efficient delivery to the browser.

Current version: 0.7.1 [the 0.5.x+ branch is not backwards compatible with earlier versions. See Change Log below for more details]


  • Allows you to write js modules without the module boilerplate (similar to Node.js)
  • Resolves js module dependencies automatically
  • Supports lazy runtime evaluation by storing js modules as strings
  • Compiles CoffeeScript, Stylus, and Less source files
  • Concatenates js modules into a single file
  • Runs js and css code through linters to check for syntax errors
  • Watches for source changes and builds automatically
  • Refreshes connected browsers after each change
  • Inlines css @imports automatically
  • Supports execution of a test script after each build
  • Copies libraries from GitHub to your project
  • Copies assets from a local destination to your project


Use the -g global flag to make the buddy(1) command available system-wide:

$ npm -g install buddy

Or, optionally, add buddy as a dependency in your project's package.json file:

  "name": "myproject",
  "description": "This is my web project",
  "version": "0.0.1",
  "dependencies": {
    "buddy": "0.5.0"
  "scripts": {
    "install": "./node_modules/buddy/bin/buddy install",
    "build": "./node_modules/buddy/bin/buddy build",
    "deploy": "./node_modules/buddy/bin/buddy deploy"

...then install:

$ cd path/to/project
$ npm install


Usage: buddy [options] <command> [path/to/buddy.js or path/to/buddy.json or path/to/package.json]>


  install [config]       install dependencies
  build [config]         build js and css sources
  watch [config]         watch js and css source files and build changes
  deploy [config]        build compressed js and css sources
  ls                     list all previously created files and directories
  clean                  remove all previously created files and directories


  -h, --help      output usage information
  -V, --version   output the version number
  -c, --compress  compress output for production deployment
  -l, --lint      check output for syntax and logic errors
  -r, --reload    reload all connected live-reload clients on file change during watch
  -t, --test      run test command on build completion
  -L, --lazy      convert js modules for lazy evaluation
  -v, --verbose   print all messages for debugging


The only requirement for adding buddy support to a project is the presence of a buddy.js/buddy.json/package.json(with buddy entry) file in your project root:

// Project build configuration. = {
  js: {
    // Directories containing potential js source files for this project.
    sources: ['a/coffeescript/source/directory', 'a/js/source/directory'],
    // One or more js build targets.
    targets: [
        // An entrypoint js (or equivalent) file to be wrapped in a module definition,
        // concatenated with all it's resolved dependencies.
        input: 'a/coffeescript/or/js/file',
        // A destination in which to save the processed input.
        // If a directory is specified, the input file name will be used.
        output: 'a/js/file/or/directory',
        // Targets can have children.
        // Any sources included in the parent target will NOT be included in the child.
        targets: [
            input: 'a/coffeescript/or/js/file',
            output: 'a/js/file/or/directory'
        // Files are batch processed when a directory is used as input.
        input: 'a/coffeescript/or/js/directory',
        output: 'a/js/directory',
        // Skips module wrapping (ex: for use in server environments).
        modular: false
  css: {
    // Directories containing potential css source files for this project.
    sources: ['a/stylus/directory', 'a/less/directory', 'a/css/directory'],
    // One or more css build targets
    targets: [
        // An entrypoint css (or equivalent) file to be processed,
        // concatenated with all it's resolved dependencies.
        input: 'a/stylus/less/or/css/file',
        // A destination in which to save the processed input.
        // If a directory is specified, the input file name will be used.
        output: 'a/css/file/or/directory'
        // Files are batch processed when a directory is used as input.
        input: 'a/stylus/less/or/css/directory',
        output: 'a/css/directory'

// Project dependency configuration.
exports.dependencies = {
  // A destination directory in which to place third-party library dependencies.
  'a/vendor/directory': {
    // An ordered list of dependencies
    sources: [
      // A github user/repo.
      // Install the 'browser-require' source when using Node-style modules.
      // A named library with or without version (ex: jquery@latest, backbone, backbone@1.0.0).
      // Version identifiers follow the npm semantic versioning rules.
    // Dependencies can be packaged and minified to a destination file
    output: 'a/js/file'
  // A destination directory in which to place source library dependencies.
  'a/source/directory': {
    sources: [
      // A github user/repo.
      // Will use the 'main' or 'scripts' properties of
      // components.json or package.json to identify the file to install.
      // A github user/repo with specific file or directory locations.
      // A local file or directory to copy and install.

// Project settings configuration.
exports.settings = {
  // Run a command after build
  test: 'command --flags',
  // Override the default plugins, and/or include custom plugins.
  plugins: {
    js: {
      // Append one or more js compilers to the default 'coffeescript'.
      compilers: ['a/file', 'another/file'],
      // Change the default 'uglifyjs' compressor to a custom specification.
      compressor: 'a/file',
      // Change the default 'jshint' linter to a custom specification.
      linter: 'a/file',
      // Change the default 'node' module type to 'amd' or a custom specification.
      module: 'amd'
    css: {
      // Append one or more css compilers to the default 'stylus' and 'less'.
      compilers: ['a/file', 'another/file'],
      // Change the default 'cleancss' compressor to a custom specification.
      compressor: 'a/file',
      // Change the default 'csslint' linter to a custom specification.
      linter: 'a/file'



Project Root: The directory from which all paths resolve to. Determined by location of the buddy.js configuration file.

Sources: An array of directories from which all referenced files are retrieved from. Note: A js module's id is derived from it's relative path to it's source directory.

Targets: Objects that specify the input and output files or directories for each build. Targets are built in sequence, allowing builds to be chained together. Note: A js target can also have nested child targets, ensuring that dependencies are not duplicated across related builds.

Target parameters:

  • input: file or directory to build. If js (or equivalent) file, all dependencies referenced will be concatenated together for output. If directory, all compileable files will be compiled, wrapped in module definitions (js), and output to individual js/css files.

  • output: file or directory to output to.

  • targets: a nested target that prevents the duplication of source code with it's parent target.

  • modular: a flag to prevent js files from being wrapped with a module definition.


Each js file is wrapped in a module declaration based on the file's location. Dependencies (and concatenation order) are determined by the use of require() statements:

var lib = require('./my/lib'); // in current package
var SomeClass = require('../someclass'); // in parent package
var util = require('utils/util'); // from root package

var something = new SomeClass();

Specifying a module's public behaviour is achieved by decorating an exports object:

var myModuleVar = 'my module';

exports.myModuleMethod = function() {
  return myModuleVar;

...or overwriting the exports object completely:

function MyModule() {
  this.myVar = 'my instance var';

MyModule.prototype.myMethod = function() {
  return this.myVar;

module.exports = MyModule;

Each module is provided with a module, exports, and require reference.

When require()-ing a module, keep in mind that the module id is resolved based on the following rules:

  • packages begin at the root folder specified in buddy.js > js > sources:
'Users/alex/project/src/package/main.js' > 'package/main'
  • uppercase filenames are converted to lowercase module ids:
'my/package/Class.js' > 'my/package/class'

See node.js modules for more info on modules.

NOTE: require boilerplate needs to be included on the page to enable module loading. It's recommended to install a library like popeindustries/browser-require.


Dependency resources are installed from local locations or remotely from Github.

Sources: An array of local or remote resource locations.

  • destination: each group of sources will be installed to the project relative location specified.

  • identifier: github username/repo identifiers are preferred, but it is also possible to use identifiers from the bower package manager: 'jquery', 'backbone', 'underscore'

  • versioning: github sources can specify a version by appending @ and a npm-style symantic version: '*', '1.2.3', '1.x', '~1.2.0', '>=1.2.3'

  • resources: specific resources can be specified by appending # and a list of | separated relative file or directory locations: 'username/repo#a/file/or/directory|another/file/or/directory'

Output: A file destination to concatenate and compress the source contents. The order of sources determines the content order.


Copy project boilerplate from a local directory:

exports.dependencies = {
  '.': {
    sources: ['../../boilerplate/project']

Grab js dependencies to be installed and packaged for inclusion in html:

exports.dependencies = {
  // install location
  'libs/vendor': {
    sources: [
      // library for require boilerplate
      // jquery at specific version
    // packaged and compressed
    output: 'www/assets/js/libs.js'

Grab sources to be referenced in your builds:

exports.dependencies = {
  // install location
  'libs/src/css': {
    sources: [
      // reference the lib/nib directory for installation

Compile a library, then reference some library files in your project: = {
  js: {
    sources: ['libs/src/coffee', 'libs/js', 'src'],
    targets: [
        // a folder of coffee files (including nested folders)
        input: 'libs/src/coffee',
        // a folder of compiled js files
        output: 'libs/js'
        // the application entry point referencing library dependencies
        input: 'src/main.js',
        // a concatenation of referenced dependencies
        output: 'js/main.js'

Compile a site with an additional widget using shared sources: = {
  js: {
    sources: ['src/coffee'],
    targets: [
        // the application entry point
        input: 'src/coffee/',
        // output to main.js (includes all referenced dependencies)
        output: 'js',
        targets: [
            // references some of the same sources as
            input: 'src/coffee/',
            // includes only referenced dependencies not in main.js
            output: 'js'


0.7.1 - February 16, 2013

  • added support for definining configuration in package.json under a buddy entry
  • fixed dependency install error for zipballs that don't match their unzipped folder names
  • upgraded dependencies

0.7.0 - January 7, 2013

  • bye bye CoffeeScript - migrated to js only source
  • upgraded dependencies

0.6.11 - December 21, 2012

  • fix css comment removal deleting base64 content

0.6.10 - December 21, 2012

  • updated Uglify-js compressor to 2.0

0.6.9 - December 14, 2012

  • fixed watch not adding new file during renames

0.6.8 - December 13, 2012

  • fixed install crash
  • install now overwrites previously downloaded resources
  • properly handle duplicate @import rules while inlining

0.6.7 - December 11, 2012

  • added --lazy option for generating js modules for lazy evaluation; module contents are encoded as strings to be passed to a Function constructor on first require()

0.6.6 - December 6, 2012

  • added live-reload support for watch command with --reload
  • re-enabled linting support

0.6.5 - December 5, 2012

  • fix for watch command firing repeated change events
  • fix for watch command not properly building targets on change
  • fix for child target building shared resources

0.6.4 - December 4, 2012

  • fix for --test not displaying both stdout and stderr
  • added wrapping of batch files in module definitions if options.modular is not false
  • fix for building targets that contain no source

0.6.3 - December 4, 2012

  • fix for watch command attempting to watch a source that doesn't exist
  • added support for default json config file type

0.6.2 - December 4, 2012

  • fix for css @import inlining

0.6.1 - December 3, 2012

  • added --test to watch command

0.6.0 - December 3, 2012

  • complete rewrite for async file operations
  • added --test flag for executing a command after build
  • added --verbose flag for outputting detailed notifications during build
  • added ls command to list all generated files
  • added inlining of '@import' rules for all css source types
  • simplified dependency resource parsing on install; only parse 'main' field in component.json/package.json

0.5.4 - November 23, 2012

  • regression fix for clean command
  • improved .buddy-filelog force clean
  • improved notifications for install and clean commands

0.5.3 - November 23, 2012

  • refactored install command behaviour; no longer uses git operations, changed syntax for specifying version ('@') and resources ('#'), added ability to list several resources [breaking change]
  • .buddy-filelog now stores relative paths for compatibility on different systems
  • file deletions limited to resources under the project root

0.5.2 - Novemver 20, 2012

  • added watch command; handle add, remove, and change of source files

0.5.1 - Novemver 14, 2012

  • added clean command to remove all generated files
  • added hidden .buddy-filelog file for tracking files changes between sessions
  • fix for false-negative module wrapping test

0.5.0 - November 13, 2012

  • compile command renamed to build [breaking change]
  • changed module naming for compatibility with recent versions of Node.js (camel case no longer converted to underscores) [breaking change]
  • changed configuration file type to 'js' from 'json'; added dependencies and settings [breaking change]
  • changed configuration target parameters to input/output from in/out [breaking change]
  • changed configuration target parameter to modular from nodejs [breaking change]
  • concatenated js modules no longer self-booting; need to require('main'); manually [breaking change]
  • require boilerplate no longer included in generated source; install popeindustries/browser-require or equivalent [breaking change]
  • removed watch command (temporarily) [breaking change]
  • added install command and project dependency management
  • added plugin support for compilers, compressors, linters, and modules; added support for custom plugins
  • added code linting
  • all errors now throw
  • complete code base refactor


(The MIT License)

Copyright (c) 2011 Pope-Industries <>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.


Something went wrong with that request. Please try again.