Chug

Chug is a caching build system. It compiles, minifies, and caches your project's assets so they can be served directly from cache, eliminating the unnecessary step of saving your files to a build directory.

Quick Start

Install chug in your project:

npm install --save chug

Chug is a function with chaining methods, and you can use it inside your Node server. Calls to chug return a Load, which is a list of assets, very similar to the way jQuery returns an object containing a list of DOM elements. Operations on a Load are chained asynchronously, and they iterate over Asset and File objects inside the load.

If your scripts directory contains some CoffeeScript that you're using along with jQuery, and you want to compile your CS, concatenate it with JS, and serve it from Express as a single file which gets reloaded when you make changes, you can use the following:

var server = require('express')();
var chug = require('chug');

chug.setServer(server);

chug(['node_modules/jquery/dist/jquery.js', 'scripts'])
  .compile()
  .watch()
  .concat()
  .route('/all.js');

The chug function

The chug module exports a function which returns an object called a Load. (Chug a load, eh?) A load contains an array of assets that can be compiled, minified, concatenated, etc. There are several types of arguments that can be passed into chug.

chug(Array)

When you chug an array, it recursively chugs each element of the array into the load. This happens asynchronously, so module order is not guaranteed.

chug(string)

When you chug a string, it resolves to the file system. If the string does not begin with a slash, chug prepends the current working directory. Chug loads the path if it is a file or recursively chugs its contents if it is a directory.

Load

.ignore(string|RegExp filenameOrPattern)

Adds a filename or pattern to be ignored while chugging directories.

.each(function callback)

Waits until all assets are loaded, then iterates over them with a callback that takes an asset argument.

.then(function callback)

Waits until all assets are loaded, then runs a callback.

.compile([Object options])

Runs compile on each asset, using each, with optional compilation options.

.minify()

Runs minify on each asset, using each.

.gzip()

Runs gzip on each asset, using each.

.replace((string|RegExp) pattern, (string|function) replacement)

Replaces the contents of each asset using string.replace(pattern, replacement). This includes base, compiled, minified, shrunken and gzipped contents.

.watch()

Puts a fs.watch on the files and directories that were added to the Load. When changes occur, the affected assets are reloaded, then the load re-runs its chain of actions. Additionally, the location of the most recently modified asset is stored in chug.changedLocation.

.require()

Loads each asset as a Node.js module.

.route([string path])

Adds routes to the server that was linked to chug with the setServer method. It uses server.get, so Express-ish servers are supported. If a path is specified, it is used. If not, chug will use the asset location as the URL. The asset location is either the filePath or a location specified in a concat call.

.concat([Load load])

Creates a concatenation of all assets from the load on which concat was called. The optional load argument, if specified, will cause the new asset to be added to an existing load rather than the default behavior of returning a new load with a single asset.

.sort(customSortFunction)

Apply a custom sorting function for ordering the assets in a load.

.shrink()

Uses Chug's shrinker to build a dictionary of terms that match a pattern, such as having a leading underscore: /_[A-Z][_A-Z0-9]+/i. Each occurrence is replaced with a short name containing one or more lowercase letters. This can be used to replace classes, IDs and properties in minified JS and CSS since they wouldn't be replaced by UglifyJS or CSSO.

.cull(string key, string value)

If you would like to designate certain sections of code as applying only to certain environments or certain browsers, you can put "cull" comments around your code.

var env = 'prod';

//+env:dev
env = 'dev';
//-env:dev

//+browser:ie6
window.console = {
  log: function () {
    // Srsly?
  }
};
//-browser:ie6

Calling load.cull('env', 'dev').cull('browser', 'chrome') on the code above would result in env being set to dev and the native console remaining intact. You can also use a comma-delimited value in your comment, so that multiple cull keys will leave the code intact.

//+env:dev,debug
verbose = true;
//-env:dev,debug

.wrap()

Wraps javascript asset's content or compiled content in closure.

.write([directory, filename][, mode])

Writes one or more assets to files. If the directory and filename are provided they will determine the write location, otherwise the asset location is used. The mode argument can be null or "compiled" or "minified", and it specifies which version of the content should be written to file.

.getLocations()

Returns an array of the locations of the assets in the load.

.getTags([string path])

Returns a string of HTML, containing script tags and link tags for any JS and CSS assets in the load. The optional path argument prepends a path to the location of those assets.

API

The chug function is also an object with several methods.

setServer(Object server)

When you pass an Express-like server to setServer, you can then call route on any assets that you'd like to route via server.get.

setLog(Object log)

Set a log that exposes log.error(message) to override the default console log.

setCompiler(string fileExtension, string moduleName, targetLanguage)

If you are using a file extension whose compiler has the same name, then chug will require it automagically.

// This will call require('jade')
chug('page.jade').compile();

However, if you want to use a compiler with a different file extension, you can call setCompiler first.

// This will use require('marked') to compile .md
chug.setCompiler('md', 'marked');
chug('README.md').compile();

In addition, if you specify a targetLanguage, assets with the specified fileExtension can be seen as having the specified targetLanguage.

setMinifier(string language, string moduleName)

The default minifiers for JS and CSS in Chug are uglify-js and csso. If you would like, for example, to minify your CSS using clean-css instead, you could set clean-css as your CSS minifier.

chug.setMinifier('css', 'clean-css');
chug('test.css').minify();

Note: The language value for JavaScript is "js" rather than "javascript".

enableShrinking()

Shrinking is power feature for minifying class names, IDs and object properties in front-end assets. Just name any classes, IDs and properties with names like _hidden or _borderBox or _panel2 or basically anything that starts with an underscore followed by a capital letter, followed by at least one more capital letter, underscore or number. When you have shrinking enabled, it will happen as a post-minification step, so be sure to minify all of your assets so their IDs and classes will match.

enableUse

Chug's "@use" functionality is an alternative to common JS require statements. When enableUse is set to true, assets will be searched for @use annotations inside comments. The @use annotations serve as guidance for asset ordering within loads, and they also load assets that were referenced but didn't yet exist in the load. Paths can be specified with leading "./" for the current directory, or "../" to back up one or more directories, or "module-name" to pull in a Node module dependency.

Acknowledgements

We would like to thank all of the amazing people who use, support, promote, enhance, document, patch, and submit comments & issues. Chug couldn't exist without you.

Additionally, huge thanks go to TUNE for employing and supporting Chug project maintainers, and for being an epically awesome place to work (and play).

MIT License

Copyright (c) 2014 Sam Eubank

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.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

How to Contribute

We welcome contributions from the community and are happy to have them. Please follow this guide when logging issues or making code changes.

Logging Issues

All issues should be created using the new issue form. Please describe the issue including steps to reproduce. Also, make sure to indicate the version that has the issue.

Changing Code

Code changes are welcome and encouraged! Please follow our process:

1. Fork the repository on GitHub.
2. Fix the issue ensuring that your code follows the style guide.
3. Add tests for your new code, ensuring that you have 100% code coverage. (If necessary, we can help you reach 100% prior to merging.)
   • Run npm test to run tests quickly, without testing coverage.
   • Run npm run cover to test coverage and generate a report.
   • Run npm run report to open the coverage report you generated.
4. Pull requests should be made to the master branch.

Contributor Code of Conduct

As contributors and maintainers of Chug, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

If any participant in this project has issues or takes exception with a contribution, they are obligated to provide constructive feedback and never resort to personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, edits, issues, and other contributions that are not aligned with this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

We promise to extend courtesy and respect to everyone involved in this project regardless of gender, gender identity, sexual orientation, ability or disability, ethnicity, religion, age, location, native language, or level of experience.