Building a Couchapp with Soca Part 2.5: Updates!!!

Soca 0.2.0

One of the changes you’ll run into with the new version of Soca is the new format of the Jimfile, which went from a flat text file format to JSON. This is a very welcomed change, IMHO, since this new format allows you to break up your dependencies into sections, and in turn, into separate JavaScript files rather than one large one. For instance, you could break up your JavaScript into core, plugins, and application groups. The resulting Jimfile would look something like:

{
  "bundle_dir": "js",
  "compressed_suffix": ".min",
  "vendor_dir": "js/vendor",
  "bundles": {
    "core": [
      "sha1",
      [ "jquery", "1.4.4" ],
      [ "jquery.couch", "0.11" ],
      [ "sammy", "0.6.3" ]
    ],
    "plugins": [
      [ "sammy.mustache", "0.6.3" ],
      [ "sammy.couch", "0.1.0" ],
      [ "jquery.embedly", "2.0.0" ],
      [ "jquery.h5validate", "0.5.0" ],
      [ "inflection", "r38" ]
    ],
    "application": [
      "js/helpers/form",
      "js/helpers/paginator",
      "js/app",
      "js/models/article"
    ]
  }
}

Note that you can call jim with update_jimfile to convert your old Jimfile to JSON. Running jim bundle will generate core.js, plugins.js, and application.js.

You might expirience some bumps in the road during the upgrade, such as errors complaining about not being able to find node.js on your system, particularly when trying to run soca push. The CoffeeScript plugin declaration inside of hooks/before_build.rb causes this. Simply get rid of the line that declares it as a plugin dependency if you’re not using CoffeeScript in your application.

Loading Scripts with yepnope.js

Now you have several smaller files instead of one huge one to declare on your page. While this is more manageable, it introduces a problem: more requests to the server when loading a page. Is this bad? Not exactly. Contrary to popular belief, loading several files as opposed to one large one yields better performance in most cases. So, we’ll do one better and use an asynchronous script loader to load our scripts. Enter yepnope.js. To use yepnope in your couchapp, download the script and place in the js/vendor directory. Since we are using yepnope to load our scripts, we can exclude it from the Jimfile, effectively preventing it from being bundled with other scripts. The html for your page might end up looking similar to this:

<script src="/js/vendor/yepnope-1.0.1-min.js" type="text/javascript"></script>
<script type="text/javascript">
    yepnope({
        load: [ 
            "/js/core.js",
            "/js/plugins.js",
            "/js/application.js",
            "{{#js}}{{js}}{{/js}}"
        ]     
    }); 
</script>

Using npm to Bundle Dependencies

In the previous article, I talked about using node.js to send emails from your couchapp. I described using ndistro to package any dependencies your mail script might have, along with modifying the load path so your script would find the dependant modules. Modifying the load path is a BIG no-no, it turns out. Thankfully, there’s a better way of doing all this. npm has the ability to bundle any dependent modules into a node_modules directory, which is one of the locations node looks up when loading non-native modules. Replacing the ndistro command of part 2 we get:

$ npm bundle install emailjs

Once npm succeeds in installing your bundle, remove this top line from your script as it is no longer necessary:

require.paths.unshift(__dirname + "/lib/node");

Wrappin’ Up

This post walked you through upgrading to soca 0.2.0, as well as using some of its new awesomeness. We also looked at how to bundle any module dependencies to any node.js scripts serving as CouchDB external processes using npm.