There's a lot more to making JavaScript apps than writing JavaScript. StealJS is a collection of command and browser based JavaScript utilities that make building, packaging, sharing, and consuming JavaScript applications easy.

Download

stealjs-beta-1.zip

Features

StealJS is made of several components:

Dependency Management

The steal script is a script loader and dependency management tool. Features:

• Load JavaScript, CSS, Less, CoffeeScript, and a variety of client-side templates.
• Load files relative to the current file, steal's root folder, your server, or from other domains.
• Load a single file only once (the whole dependency management thing).

steal('dojo','jquery','prototype');

JS/CSS Concatenation and Compression

Steal's build plugin compresses an application into a single minimized JavaScript and CSS file. Features:

• Works with any application, even ones not using the steal script.
• Configurable compressors (defaults to Google Closure).
• Compresses Less and CoffeeScript.
• Pre-processes and compresses client-side templates (templates don't have to be parsed or included with the page).
• Expandable architecture makes it easy add other file types to the build script.
• Can intelligently combine shared dependencies into separate files for caching.

./js steal/buildjs mypage.html

Code Generators

Steal's generate plugin makes it easy to get started developing. Features:

• Creates folders, files and scripts your app needs.
• It's very easy to make custom generators.

./js steal/generate/app myapp

Package Management

Steal's get plugin is a very basic JavaScript version of ruby gems. Features:

• Download and install plugins from remote SVN or GIT repositories.
• Installs dependencies.

./js steal/getjs http://github.com/jupiterjs/funcunit

Code Cleaner

Steal clean beautifies your code and checks it against JSLint.

./js steal/clean path/to/page.html

Logging

Steal dev logs messages cross browser. Messages are removed in production builds.

steal.dev.log('something is happening');

Why

StealJS is an extremely strong attempt at solving a few of the the most core problems in JavaScript development:

Development vs Production

There's a tension between development and production JavaScript needs. When developing JavaScript, you want:

• Lots of logically separated files.
• Changes in a file to only require a refresh of the browser. (It's JavaScript not JavaCompile!)

This is in contrast to production where you want a few compressed and cacheable files.

Steal makes this easy with not only JavaScript, but with other resources like CSS, client side templates, Less, and CoffeeScript!

Yes, this means what you think it does. You can edit CoffeeScript/Less/template/CSS files and just refresh the browser to see changes. When you finally make a production build, steal will convert, package, and compress these files with your other JavaScript and CSS files.

Optimized Websites

There's also tension between script loading performance and caching. You want to:

• Have as few http requests as possible.
• Exploit the cache.

This is especially problematic when multiple pages have shared dependencies. Lots of shared scripts better exploit the cache, but also increase the number of requests.

StealJS makes it easy to find the perfect balance. It can build apps for multiple pages at the same time, understand the shared dependencies, and create cacheable shared downloads.

Framework Agnostic

Most server frameworks come with varying levels of similar functionality. Ruby on Rails is particularly great and bundling Less CSS and JavaScript.

But, what if you wanted to bundle the same Less files with ASP.NET MVC?

StealJS works with any server framework. As we (or mabye you) add new features, those will be available to users of any web framework.

Resources

• Documentation
• Github Repository
• Website (a work in progress).
• Get Help (on the JavaScriptMVC forums).

Use

Download steal and unzip it into a public folder where you will have JavaScripts. You should see something like:

/your_public_folder

  /steal

  /js.bat

  /js

If you don't already, make sure you have Java 1.6 installed.

Using Generators

The easiest way to create a new app that uses steal is to use steal.generate to create an application skeleton. Open a command line to your public folder. In windows write:

js steal\generate\app myapp

In Mac/Linux write:

./js steal/generate/app myapp

Warning: The remainder of this guide only shows the windows command. Mac/Linux users should change js to./js and \ to /. (We make the Mac/Linux people figure it out because they are smarter :-).

This creates a myapp folder in your public directory that looks like:

/myapp

  /docs

  /scripts

     /build.js

     /clean.js

  /test

  /resources

     /example.js

     /example.coffee

     /example.less

  /myapp.html

  /myapp.js

  /myapp.css

Dependency Management and Script Loading

If you open myapp.html in a web browser, you should see something like:

**** This won't work on the filesystem from Chrome because it has draconian XHR limitations. If you run it from a server, it will work perfectly.*

Now open myapp.html in a text editor, you will find a script tag like:

<script type='text/javascript'

        src='../steal/steal.js?myapp/myapp.js'></script>

This loads the steal script. The steal script is what does dependency management. The myapp/myapp.js tells the steal script to load your app at myapp/myapp.js.

Open myapp/myapp.js. In it you'll see something like:

steal( 'resources/example' )              // 1

  .css( 'myapp' )                         // 2

  .plugins(

      'steal/less',

      'steal/coffee' )                    // 3

  .then(function(){                       // 4

      steal.coffee('resources/example')   // 5

        .less('resources/example');       // 6

  });

This:

1. Loads 'myapp/resources/example.js'.
2. Loads 'myapp/myapp.css'
3. Loads 'steal/less/less.js' and 'steal/coffee/coffee.js'
4. Adds a function to be called back once all prior files have been loaded and run.
5. Loads 'myapp/resources/example.coffee'.
6. Loads 'myapp/resources/example.less'.

**** This callback is needed because script loading is not synchronous. The 'steal/coffee' and 'steal/less' plugins add steal.coffee and steal.less.****

The steal script provides a number of helper functions to make loading scripts very easy. Once you have loaded all the scripts for your app, it's time to build it.

JS/CSS Concatenation and Compression

If you used the generators to create your application, compressing your app is very straightforward:

js myapp/scripts/build.js

This packages your app into myapp/production.js and myapp/production.css.

To uses these files instead of all your uncompressed files, change your page to load steal.production.js instead of steal.js:

<script type='text/javascript'

        src='../steal/steal.production.js?myapp/myapp.js'>

</script>

Reload myapp.html and you should see it load only 2 JavaScript files and one CSS file.

Package Management

Steal.get downloads and installs plugins from a url. Typically it's run from the steal/getjs script.

The following copies the FuncUnit repo to a local funcunit folder.

js steal\getjs http://github.com/jupiterjs/funcunit -name funcunit

Official Plugins

Steal maintains a list of official plugins compatible with steal development. You can install these just by providing their name:

js steal\getjs funcunit

The following are the list of official StealJS plugins. As StealJS itself is in Beta, the following plugins should not be considered production ready:

• steal - Update steal itself.
• funcunit - Functional testing platform.
• jquery - jQuery 1.4.3 and the JavaScriptMVC components.
• phui - Very early alpha UI widgets.
• documentjs - A documentation engine.
• mustache - mustache templates.
• ss/statemachine - Implements jQuery.Controller as a fininte-state-machine
• ss/router - The Sherpa routing system for jQuery.Controller

Code Cleaning / JSLinting

Steal clean uses JS Beautifier to clean your code and JSLint to check it for trouble spots like global or unused variables.

Cleaning a Single Script

To clean a single script, you can write:

js steal/cleanjs path/to/my/script.js

It will replace the script with a beautified script. If you want to also add JSLint (feelings beware), run it with:

js steal/cleanjs path/to/my/script.js -jslint true

Cleaning a StealJS app

If you used the generator to build your app, you can clean myapp's scripts with:

js myapp/scripts/clean.js

Add JSLint with:

js myapp/scripts/clean.js -jslint true

Logging

Finally, a small but nice feature of StealJS is that you can leave log messages without worrying that they show up in your production build. For example, steal.build will remove the following from the production build.

steal.dev.log("Something has happened"); //***

**** If you want to see this work, change to development mode and open Firebug.*

Conclusion

We built StealJS to provide a single solution to many of the script management problems we faced with our client work. I hope it helps you in the same way it has helped us - turning around higher quality apps faster.

In the next two weeks, we plan to release a production StealJS. This will be followed by months of adding new tools, resources, and documentation.

In the future, we hope to work with other projects like LabJS, CommonJS, and RequireJS, to offer a 'standard' solution to the problems addressed by StealJS.