Local JS Bin: the detailed how-to

JS Bin is a Node project.

Installation requires just two steps:

1. Installing code
2. Configuration

For the simplest install process we recommend using Node with SQLite.

Historically, JS Bin v1, v2 and the first release of v3 had support for PHP. PHP is no longer supported. If you want to install JS Bin using PHP, I’m afraid you’re on your own. There are some old docs that can help, but the project has long surpassed PHP’s functionality. If you want to risk the PHP version, grab v3.0.0 here, warts an all.

Installing

Node

Install Node version 0.10.x, which will give you the node and npm programs. (Installing JS Bin on newer versions of Node is not supported and may fail; consider using nvm to install multiple versions of Node on your machine.)

You can (and should) install JS Bin directly from npm using the following command:

npm install -g jsbin

This will automatically install all the dependancies.

If you’re installing JS Bin for development (and hopefully contribution), clone the project from github:

git clone https://github.com/jsbin/jsbin.git
cd jsbin
npm install

If you plan to build and test for production, see the section at the end.

Configuration

JS Bin comes with a default config file. Should you want to customise how JS Bin runs, you should create a config.local.json (which could be based on config.default.json) and then when you run the jsbin command you must tell the application where your local config is using the following command:

$ JSBIN_CONFIG=/PATH/TO/config.local.json jsbin

There are a number of options that you can change to configure JS Bin to your needs. The property names, meaning and possible values have been listed below:

• env: development or production

This is whether you want to run in development mode (recommended) or production. Production mode requires that you build a single JavaScript file for JS Bin to run from. This is only required if you plan to run JS Bin as a service to a larger public audience. Building for production is detailed in a section later on.

• url: Object - detailed next

This is an object controlling how URLs are generated in JS Bin. If you plan to run JS Bin from a subdirectory, you must change these settings.

• url.host: The host you will access JS Bin on, eg. jsbin.dev is what we use offline. If you want to include a port number here you should do, eg. jsbin.dev:8000 will request JS Bin over port 8000.
• url.prefix: / or your subdirectory that JS Bin should be accessed from. For instance, if you run JS Bin under http://remysharp.com/jsbin the url.prefix value must be /jsbin/.
• url.ssl: false or true whether you want to run JS Bin over SSL.
• url.static: false or a url, such as http://static.jsbin.dev:8000/jsbin/. This will control where static assets are served from. If the value is false, they will be served from the same path as dynamic content.

Running behind a proxy

JS Bin will run behind a proxy, indeed our production version of JS Bin is behind a proxy.

The PORT on the command line takes precedence over the config variable. This means in your config, you set the url to be the user facing port (typically port 80, so no port required), and then JS Bin will listen on the port you gave at the envinoment level.

So to proxy jsbin.com to a localhost:8000 (using something like nginx to do the proxying), the config would look like (this snippet of config.local.json):

"url": {
  "host": "jsbin.com",
  "prefix": "/",
  "ssl": false
},

Note that in the above config, jsbin.com is what is used in the HTML and JavaScript, so this is the client facing url. Next, running JS Bin behind a proxy is as simple as:

$ PORT=8000 JSBIN_CONFIG=~/config.local.json jsbin

Now the jsbin node process is listening on port 8000, but the client facing urls are all port 80.

Building for production

JS Bin’s build process uses Grunt, so assuming you’ve cloned a copy, you will need the dev dependancies and the grunt cli:

npm install -g grunt-cli
npm install --dev
grunt build

This will generate the public/js/prod/ directory and read the version in the package.json file to generate to build a number of files:

1. jsbin-$version.js - the uncompressed, concatted version of all the scripts from /scripts.json
2. jsbin-$version.min.js - the production compressed version of jsbin, used in the editor
3. jsbin.map.json - the sourcemaps file (useful for debugging in live)
4. runner-$version.js - the runner script, used to generate the output of the user’s code in an iframe
5. runner-$version.min.js - the production version of the runner

Finally, ensure either the config.local.json’s env property is set to “production” or you can run JS Bin in production via the envinoment:

$ NODE_ENV=production node .

And that’s it.