nodeify

Bring CLI testing and npm modules to your JavaScript.

Requirements

Install Node.js and npm:

$ port install nodejs
$ curl http://npmjs.org/install.sh | sh

Nodeify is designed to work with Rails 3.1 and higher.

Installation

In your Gemfile:

gem 'nodeify'

Run:

$ bundle update
$ rails g nodeify:install

Usage

App-specific JavaScript

As with any Rails JS with the asset pipeline, put your app-specific JavaScripts in app/assets/javascripts directory.

require()

Under the standard Rails asset pipeline regime, the sprockets gem is used to manage JavaScript file loading/dependencies through the //= require xxx syntax. With Nodeify, your javascripts fit into the standard CommonJS modules framework. You can use var MyLib = require('./xxx') statements that are relative to your app/assets/javascripts directory and lib/assets/javascripts directory (both paths are added to NODE_PATHS). You can also use require() to load Node.js npm modules (see below).

Understanding require()

The CommonJS require() works a bit differently than Ruby's require or the sprockets //= require. CommonJS isolates modules (any code grouped into a file) into its own environment. Variables defined local to the module will only be available in that module. To expose certain objects...

TODO: Explanation

In the meantime, google CommonJS modules.

Node modules

In your app's root directory, add any npm module dependencies to package.json file, just like any Node.js server app or npm module. Nodeify will add a default package.json for you. Npm dependencies look like:

"dependencies": {
  "jquery-browserify": ">= 1.3.x",
  "jsonpath": "*"
},
"devDependencies": {
  "browserify": "*"
}

Once you've updated dependencies, you can install the newest modules with

$ npm install

Asset Pipeline Misc.

Nodeify integrates seamlessly with the standard asset pipeline workflow. The only difference is the use of CommonJS require() instead of sprockets' require.

Testing

Testing tasks are defined in the Cakefile, according to whether jasmine (default) or vows is selected as the testing framework. Run your JavaScript tests with cake test. Individual files can be tested with cake test -p spec/MyClassSpec.js (jasmine) or cake test -p test/my-class-test.js (vows).

Contributing to nodeify

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.