gears / gears

Compiles and concatenates JavaScript and CSS assets. Inspired by Ruby's Sprockets.

Gears

Gears is a library to compile and concatenate JavaScript and CSS assets, highly inspired by Ruby's Sprockets. You can also write scripts, styles and client templates using CoffeeScript, Handlebars, Stylus, Less, and compile them using external packages (gears-coffeescript, gears-handlebars, gears-stylus, gears-less). These packages already include all required node.js modules, so you don't need to worry about installing them yourself.

There is also:

• django-gears, an app for Django that integrates Gears with Django project;
• Flask-Gears, an extension that integrates Gears with Flask application;
• gears-cli, a command-line utility that compiles assets. It also can watch assets for changes and automaticaly re-compile them.

Features

• Dependency management using directives in header comments. For example:

  /* Dependencies:
   *= require jquery
   *= require underscore
   *= require backbone
   *= require_tree views
   *= require_directory templates
   */

  Six directive types is supported for now:

  • require :path: includes the contents of the asset path suffixed with the same extension as the current asset (e.g., if js/app.js.coffee has directive require views, js/views.js.coffee will be included). Supports globbing: require models/*.
  • require_directory :path: includes the contents of the every asset in the directory path with the same suffix as the current asset in alphabetical order.
  • require_tree :path: includes the contents of the every asset with the same suffix as the current asset in the directory path and all its subdirectories in alphabetical order.
  • require_self: includes the contents of the current asset at the current place. If there is no require_self directive, the contents will be appended at the end of asset.
  • depend_on :path: it is useful when you need to specify files that affect an asset, but not to include them into bundled asset or to include them using compilers. E.g., if you use @import functionality in some CSS pre-processors (Less or Stylus). Supports globbing: depend_on app/*.
  • public: mark the asset as public.
• Scripting and styling in modern languages like CoffeeScript, Stylus, Less (support for new languages can be easily added).
• Writing client templates using Handlebars.
• The list of compilers for the asset is specified with asset extensions appended to the original extension. E.g., for the asset named js/app.js.coffee CoffeeScript compiler will be used. Here are extensions for the supported compilers (through external packages):
  • CoffeeScript - .js.coffee;
  • Handlebars - .js.handlebars;
  • Stylus - .css.styl;
  • Less - .css.less.
• Caching

• Compressing. Supported compressors:

  • SlimIt (Python, 2.X only);
  • cssmin (Python, 2.X only);
  • UglifyJS (Node.js, using gears-uglifyjs);
  • clean-css (Node.js, using gears-clean-css).

  New compilers can be also easily added.

• Supports Python 3.

Installation

You can install Gears using pip:

$ pip install Gears

If you want to use node.js-dependent compilers or compressors, you need to install other dependencies:

$ pip install gears-less          # LESS
$ pip install gears-stylus        # Stylus
$ pip install gears-handlebars    # Handlebars
$ pip install gears-coffeescript  # CoffeeScript

$ pip install gears-uglifyjs      # UglifyJS
$ pip install gears-clean-css     # clean-css

Please note that all these compilers and compressors require node.js to be installed on your system.

Usage

This example compiles public assets (default: assets/js/script.js, assets/css/style.css, all assets that aren't compiled to .css or .js and assets marked as public using public directive) from assets directory to static:

import os

from gears.environment import Environment
from gears.finders import FileSystemFinder


ROOT_DIR = os.path.abspath(os.path.dirname(__file__))
ASSETS_DIR = os.path.join(ROOT_DIR, 'assets')
STATIC_DIR = os.path.join(ROOT_DIR, 'static')

env = Environment(STATIC_DIR)
env.finders.register(FileSystemFinder([ASSETS_DIR]))
env.register_defaults()

if __name__ == '__main__':
    env.save()

There is already mentioned django-gears app, which you may want to use in your Django projects.

Contributing

Feel free to fork, send pull requests or report bugs and issues on github.

gears's Issues

It seems that `require_directory` directive handles removed/renamed assets incorrectly

Branches and cache

There is a problem with the cache when working with branches.

Suppose, for example, the file 'assets/js/templates/new.handlebars' is located in the branch develop and is not yet in the branch master.

Work scenario:

1. I work in a branch develop, which contains the file 'assets/js/templates/new.handlebars'. The cache has an information about this file.
2. I checkout to the branch master, which does not contains the file 'assets/js/templates/new.handlebars'.
3. I try to collect assets. As a result, I get an error message: OSError: [Errno 2] No such file or directory: '.../assets/js/templates/new.handlebars'
4. I delete all the data in the gears_cache folder and recollect assets. Then everything works fine until a missing directory is in the cache again.

jasmine django and gears

I created a django app that integrates django, gears and jasmine for tests with Phantom JS. I'd like to move the repository to the gears organization and be added as a contributor to the project.

https://github.com/kitanata/django-gears-jasmine

Add support for cssmin as css compressor

Add support for cssmin Python library as css compressor.

Add cache to store cached items on the filesystem

It would be helpful to have simple persistent cache for command-line utility or Django's reloadable runserver, for example.

Make cache pluggable

Error after upgrade to 0.7

I upgraded from 0.6.1 to 0.7 and changed nothing else.

The three lines starting here https://github.com/gears/gears/blob/develop/gears/environment.py#L413

            basename = os.path.basename(asset_attributes.path_without_suffix)
            if not fnmatch(basename, basename_pattern) and basename != 'index':
                continue

stops everything from working. I'm not using globs. Every require'd file causes continue to happen.

Wrap modules into self calling function

Currently most of the time I have to write:

(function ($, undefined) {
    window.mymodule = window.mymodule || {};
    window.mymodule.submodule = window.mymodule.submodule || {};

    var submodule = window.mymodule.submodule;

    submodule.method = function() {
    };
}(jQuery)):

So it would be awesome if I could replace this to this:

//= require jquery import jQuery as $
//= export mymodule.submodule

var submodule = window.mymodule.submodule;

submodule.method = function() {
};

Add support for slimit as js compressor

Add support for slimit Python library as js compressor.

Less support

Current approach to compiling less files is totally broken, because:

1. If using directives, files are first compiled to css, then merged. That means it is not possible to get less variables with gears require directive
2. Because only source code is passed to less compiler, it's not possible to import any less files with "@import" statement.

I have a working prototype of compiler that can work with less files. Currently it allows for imports like:

@import "file.less"
@import "bootstrap/mixins.less"
@import "bootstrap/mixins"
@import "other_file.css.less"

Problems with my current implementation

There are few problems with my current implementation. Eg.

@import "other_file"

Should look for "other_file.css.less" and "other_file.less" but it only looks for "other_file.less" (because less compiler automatically appends .less.

css imports are not altered. To be honest, I have no idea how I should handle them (any path rewriting?).

How does it work?

Script in less.js communicates through stdin/stdout with python process. When it needs to import a .less file, it asks python process (sends a message through stdout) what is absolute path to less file.

I need to do some code cleanups and also implement "depends_on" directive, so changes to any "@import'ed" file will invalidate asset's cache.

My questions

My only question is how "@import" should behave in following situations:

@import "mydir/myfile"
@import "otherdir/otherfile.css"
@import "dir2/file2.less"
@import "dir2/file2.css.less"

I'll post my current prototype as soon as I'll deal with depend_on an cleanup my code.

SCSS Support

I built a compiler for SASS's SCSS format. Thought you might like to include it in the organization.

https://github.com/wbond/gears-scss

Add support for Python 3

Add an option to create gzipped version of public assets

If we have css/style.css and js/script.js as public assets it would be also useful to create gzipped version of them (css/style.css.gz and js/script.js.gz).