Capucine

Capucine is a command line tool for using Compass, CoffeeScript and Incloudr in any project. It is completely agnostic and there are few configuration (just a simple and understandable YAML file).

*The first goal of Capucine is to give to everyone a very easy access to modern frontend tools. *

Capucine official site

This meta-languages really solve big problems in frontend development. Some people are using them every day for a cleaner code and better collaboration.

  • Compass

Maybe you already know Sass (and Compass). If it's not the case, this blog post can be really helpful.

Understanding Sass

  • CoffeeScript

CoffeeScript is a pure JavaScript generator. Reading this post can help you to understand his goals.

Understanding CoffeeScript

  • Incloudr

Incloudr is a multiple provider JavaScript client library. It allows you to quickly download JavaScript libs from cdnjs.com, git repos, NodeJS Packages (NPM), and raw url files without the mess.

Do I need Capucine ?

Rails projects

If you are a Ruby On Rails developer, you probably do not need Capucine. Sprocket does the job. Maybe you are looking for an alternative to Sprocket ? Capucine is faster, test it. Then, you might be interested in the Incloudr part of Capucine.

More on this feature here : Incloudr, an easy way to embed JavaScript.

Others projects

If you are coding in PHP, .NET, Java, Perl, Ruby (Sinatra, Padrino, ...) or an other language, Capucine is the simplest way to use Sass and CoffeeScript ! You don't need to change anything in your application. Just provide the right paths in the capucine.yaml file, compile, and that's work.

Intallation (22 seconds)

Require :

  • Ruby 1.9.*
  • RubyGems

Tested on :

  • OSX 10.6
  • OSX 10.7
  • Ubuntu
  • Windows 7

Quick install (or update) :

gem uninstall -a -x capucine
gem update --system
gem install capucine

Maybe the capucine.yaml as change with new version. Please update it :

cd my_project/
capucine init

(edit capucine.yaml)

capucine watch

Start

This will generate a full ready-to-use project from scratch :

capucine new my_app_name

If you are already working in a project, initialize a Capucine project where you want, this will just add a capucine.yaml file in the current directory:

capucine init

The capucine.yaml file is the only required file for using Capucine.

If you want to start with another capucine.yaml , there are some templates hosted on the Capucine official Github repository. You can create yours, and use them as well.

Use your own configuration (hosted somewhere)
capucine init http://myhost.com/capucine.yaml
Use existing configurations (hosted on Github)
capucine init:django
capucine init:sinatra
capucine init:wordpress
...

Of course, you can contribute to the official repository ! Read this section

Usage

Once you have configured the capucine.yaml and write some Sass and/or CoffeeScript, you can compile the project once :

capucine compile

In developement, you might want to launch the watcher. This will compile everything once and compile files on changes (use and abuse it):

capucine watch

Let's recap

So, you can use (simple recap) :

  • Create

    cd my_current_project/

# Or

capucine new my_app_name
cd my_app_name/

  • Initialize

    # Edit the capucine.yaml file.

# Or :

capucine init
capucine init:django

  • Compile Once

    capucine compile

  • Or Watch (Stop with Ctrl + C)

    capucine watch

Incloudr

You can directly configure JS libraries you need in the capucine.yaml . Enter the output directory where you want your libs :

incloudr_output_dir: public/js_generated/modules

Your JS libraries will be download form the web and they will be move to the incloudr_output_dir directory. So, list you libs :

incloudr_libs:

    - name: jquery

The default CDN is CDNJS, and it will download the latest version. So, if you want a specific version :

incloudr_libs:

    - name: jquery
      version: 1.7.2

Need a NPMJS package ? Configure the package like this :

incloudr_libs:

    # From CDNJS :

    - name: jquery

    # From NPMJS (coming) :

    - name: underscore
      type: npm

With a specific version from NPM ? (coming) :

incloudr_libs:

    - name: underscore
      type: npm
      version: 1.3.3

Maybe you just want to include a distant JS file :

incloudr_libs:

    - name: my_lib
      source: http://site/to/my/lib.js

List all JS libraries existing on CDNJS.com :

capucine js:list

List all JS libraries existing on NPMJS.org :

capucine js:list:npm

Search a library on CDNJS (example: jquery) :

capucine js:search jquery

Search a library on NPMJS (example: underscore) (coming):

capucine js:search:npm underscore
When my lib are downloaded ?

When you type capucine compile, your Sass and CoffeeScript are compiled, and Incloudr will look at the capucine.yaml, download them, and move the files to the incloudr_output_dir directory.

When you type capucine watch, Capucine will first do a capucine compile, and next it will start the watcher.

How does it work

Capucine works on top of Compass and CoffeeScript. It use a watcher for compiling CoffeeScript on the fly and uses the official Compass watch for Sass's files. So, it generate a configuration file for Compass (config.rb).

If you activate the sass_cache options, Capucine will generate a .sass-cache/ folder in the working directory.

Tools

Since Capucine generate some needed extra files(config.rb and .sass-cache/), you can remove them with :

 capucine clean

Update the Capucine gem (will update Compass, SASS and CoffeeScript to the edge):

capucine update

If you know what you're doing, you can update them with rubygems :

gem install sass
gem install compass
gem install coffeescript

Quick Help :

capucine help

There are shortcuts :

capucine i   == capucine init
capucine n   == capucine new

capucine c   == capucine compile
capucine w   == capucine watch
capucine j   == capucine js

capucine h   == capucine help
capucine u   == capucine update
capucine cl  == capucine clean

CONFIG : capucine.yaml

All directories are relative to the root project (the parent directory of the capucine.yaml file)

Compass :

All the option are from the official Gem : Documentation here But, there are the basics :

  • sass_dir : Directory where you place your .scss / .sass files.
  • css_dir : Where your Sass will be compiled.
  • images_dir : For Compass helpers.
  • line_comments : Remove line comments for the output.
  • output_style : expanded (dev), compact, or compressed (prod).
  • sass_options : Raw Sass options. Will be passed to Compass configuration.

And :

  • use_libsass : For the future.
  • compass_plugins : A list of plugins. gem_name or plugin_name|gem_name
    Ex : - compass-capucine or - compass_twitter_bootstrap.

Import:

  • sass_import_css : True or False. For using the import system.

  • sass_import_formats : Can be css to scss, css to sass, scss to sass, or sass to scss.

  • sass_import_css_dir : The input directory for import.

  • sass_import_output_dir : Where your CSS will be compile.

CoffeeScript :

  • coffeescript_bare : Use the --bare option for CoffeeScript.
  • coffeescript_files_dir: Directory where you place your .coffee files.
  • coffeescript_output_dir : Where your .js will be generated.

Incloudr :

  • incloudr_output_dir : Where your modules will be placed.
  • incloudr_libs : A list of library to use. See the documentation above.

Contribute to the official repo

If you want to share you capucine.yaml files :
  • Fork the project.
  • Create a branch with the Template name (example: wordpress).
  • Add your capucine.yaml in the templates/ directory.
  • Edit the templates/README.md file.
  • Commit.
  • Pull Request.
  • Drink a coffee.
If you want to contribute to the core system :
  • Fork the project.
  • Create a branch with a feature name (example: github-cdn).
  • Edit.
  • Commit.
  • Pull Request.
  • Drink another coffee.

TODO

  • Add NPM support for Incloudr

  • Add JSDelivr support for Incloudr

  • Make rake tasks

  • Switch from FSSM to guard-listen

Author