Shotgun In The Browser

<< home

---

As of v7.4.3 and up, shotgun plays nice with browserify! Now you can use shotgun purely in the browser if you would like. This is not to be confused with the shotgun-client library, which is just a client interface specifically designed for when shotgun is running on the server and you'd like to use it in realtime in the browser. Using shotgun with browserify actually puts shotgun and all of your command modules in a script bundle that can be used in your web pages. There is no shotgun presence on the server in this configuration.

---

One of the things shotgun does for you when running in node is it automatically loads all your custom command modules from a directory. This makes it really easy to add/remove command modules from your app. Unfortunately the nature of the browser means there is a couple of extra steps necessary to get shotgun working. Let's go through setting up shotgun in the browser step by step.

1) Write your command modules.

Luckily, you write your command modules the same way you would if you were running them on the server, placing them all in a single directory. Don't worry about your main application file just yet, we'll do that toward the end.

2) Bundle your command modules.

$ npm install -g shotgun

When you install shotgun globally it gives you a convenient "shotgun" command line utility. This utility provides a number of helpful tools, one of them being the "bundle" ability which we'll see shortly.

The shotgun command line utility provides a bundle capability that bundles up your command modules into a single file. Remember, shotgun won't be able to access any file system while running in the browser so it won't be able to load your modules automatically. Lucky for you we've gone the extra mile to make it super easy to manually register your command modules with shotgun.

Issue the following command at the terminal:

$ shotgun bundle path/to/cmd/directory/ -o cmd-bundle.js

This will create a helper file that you can use to manually require all your command modules in your app. The file contains explicit require calls to absolute file paths for your command modules. Browserify works by parsing your script files and looking for require calls. However, it doesn't actually run your code. Because of this, browserify cannot render any require calls that are dynamic, where the path is constructed in code.

Since shotgun loads command modules dynamically by default, the command line utility generates a file with explicit require calls to an absolute path. This is how browserify will be able to include all your command modules in the bundle.

3) Write your main script file.

Our goal is to create a single script bundle that contains your entire shotgun application. We need to write a small script file to setup and configure shotgun. It will be up to you to write the rest of the code for your app so that it uses shotgun, but it should be pretty intuitive once we get this running. Create a file like the following:

// app.js

var cmdModules = require('./cmd-bundle');
var shotgun = require('shotgun');
var shell = new shotgun.Shell();
shell.registerCmds(cmdModules);
window.shell = shell;

Hopefully that is pretty straightforward to you. All we've done is require our module bundle, require shotgun, use shotgun to create a new shell instance, registered our command module bundle with the shell instance, and attached the shell instance to the window (global) object. Obviously you'll probably want to expose the shell differently depending on how you want to use it in your application. We're attaching it to window here just so it's really easy to test out this demonstration at the end.

4) Create the final bundle using browserify and add it to your web page.

$ npm install -g browserify
$ browserify app.js -o app-bundle.js

This will create a new file called "app-bundle.js". Ideally, this bundle would also probably include the rest of your application. If you're familiar with browserify it shouldn't be very difficult for you to figure out.

Now simply create a web page to add your script bundle to.

// index.html

<!DOCTYPE html>
<html>
    <head>
        <title>Shotgun in the browser!</title>
        <script src="/app-bundle.js"></script>
    </head>
    <body>
        <h3>Open the JavaScript console and type "shell" to get access to the shell instance you created.</h3>
        <pre></pre>
    </body>
</html>

5) Try it out!

Now serve up the page in whatever way you would like. The easiest way that I know of (without opening the file directly in a browser) is to use the http-server module from npm.

$ npm install -g http-server

Then you can simply run http-server from any directory on your machine and it will start a web server there to serve up the files.

$ cd your/app/directory
$ http-server

Now open your browser and navigate to http://localhost:8080. You should see a mostly blank web page telling you to open up your browser's JavaScript console. If you're using Chrome then you can find the console by going to the Chrome menu > Tools > JavaScript Console. Once there you can write JavaScript code and execute it. Remember earlier that our script bundle adds our shell instance to the global namespace (window) so all you need to type in the console is window.shell or just shell to access it.

Try typing the following into the JavaScript console:

> shell.on('log', function (text) { document.getElementsByTagName('pre')[0].innerHTML += text + '<br />'; });

That registers a listener on the shell to listen for "log" events. When one occurs we simply append the body tag with the text. Now execute a command, such as "help"...

> shell.execute('help');

...and watch the magic happen!