For a long time we’ve been struggling to manage the growing presence of JavaScript at 37signals. We needed a way to share common JavaScript components and behaviors across our applications and web sites. And we wanted the ability to organize our JavaScript source code into multiple files and folders without the overhead of including dozens of <script> tags on every page.

So we scratched the itch by creating Sprockets.

Sprockets is a Ruby library that preprocesses and concatenates JavaScript source files. It takes any number of source files and preprocesses them line-by-line in order to build a single concatenation. Specially formatted lines act as directives to the Sprockets preprocessor, telling it to require the contents of another file or library first or to provide a set of asset files (such as images or stylesheets) to the document root. Sprockets attempts to fulfill required dependencies by searching a set of directories called the load path.

It helps you turn messy JavaScript into clean modules for development and a single .js file for deployment.

Here are some of the benefits of Sprockets:

Extract reusable code and share it across multiple web sites or applications. Sprockets makes it easy to extract JavaScript plugins from your site or application and share them across your portfolio. Use your SCM to check out plugin repositories directly into your site or application. Then tell Sprockets to add the plugins to your load path. Support for asset provisioning lets you bundle CSS and images with JavaScript plugins, too.

Speed up your site by automatically concatenating JavaScript into a single file for production. Concatenating your site’s JavaScript means all your source code is cached in the browser on the first hit. It also means you reduce the number of HTTP requests necessary to load a single page. When combined with gzip compression on the web server, concatenation is the fastest way to serve JavaScript to your users.

Organize your JavaScript source code into multiple commented files and directories. Finally, an end to navigating long, difficult-to-maintain JavaScript source files. With Sprockets, JavaScript source code can live anywhere on your system, even outside your site’s or application’s document root. You’re free to split source code up into multiple files and organize those files into directories during development. You can also add as many comments as you want—they’ll be stripped from the resulting output.

Use bleeding-edge framework and library code in your application. If you use and contribute to open-source JavaScript frameworks and libraries that use Sprockets, like Prototype and, the build processes for those scripts can be integrated directly into your application. That makes it possible to track the latest development versions of your framework and library dependencies by adding their repositories to your application’s Sprockets load path.

Sprockets is compatible with the PDoc JavaScript documentation system and the JavaScript framework of your choice. If you document your JavaScript source code with PDoc, Sprockets will automatically strip documentation comments from the resulting concatenated output. You can use any JavaScript framework you like in your site or application—Sprockets is framework-agnostic.

Screencast: How we’re using Sprockets in our new marketing sites

I’ve recorded a screencast showing how we use Sprockets in our new marketing sites.

(You can watch the full-size verison on Vimeo.)

How to get Sprockets

Visit the Sprockets web site for installation and usage instructions. The source code is available on GitHub, and you can install the RubyGem with gem install sprockets.

Sprockets can be used as a Ruby library or with a simple CGI script. There’s also a Rails plugin available separately.