How to Build and Deploy Apps

BladeRunnerJS (BRJS) provides built-in support for building your application. It provides automatic versioning support and two forms of build output; static file and a packaged WAR file.

Application Versioning

When an application is built, the location of assets is auto-generated to include a version string which is the timestamp at the point the build is executed.

When you build and deploy your application the index.html aspect entry point will refer to the versioned assets (JS, CSS, HTML templates etc.).

If you build and deploy your application as a WAR, a filter is included to set caching headers. Note that index.html aspect files are not cached as they are the entry point to your application and will change on each build. The rest of the application assets will be cached.

However, if you build and deploy your application as static assets you will need to ensure that index.html aspect files are not cached by configuring your server appropriately.

Building your App

The two forms of build output that BRJS supports are:

1. Static file build for deployment on any web server or CDN
2. WAR file build for deployment on servers like Tomcat and JBoss

The command for building application is:

./brjs build-app <app-name> [<target-dir>] [-w|--war]

Where the app-name is the name of the application you wish to build and target-dir is where you want the output of the build to go. The -w or --war command allows you to set the output to be built as a WAR file.

Build as Static Files

If you wish to deploy your application to any web server or a CDN then it's likely that you'll want to use the BRJS toolkit to build your assets into concatenated file bundles that can be served as static files.

For example, in the following example the app named myapp will be built to a directory ~/brjs-apps/myapp/:

./brjs build-app myapp ~/brjs-apps

Note: in the above example ~/brjs-apps must exist

The built application will consist of a directory for each locale, an index.html application entry point and a v directory containing another directory representing the timestamp version of the build e.g. 1403275456940 is Fri Jun 20 2014 15:44:16 GMT+0100 (BST).

The structure of the contents of timestamp version directory is as follows:

• css - The bundled CSS with a file for each available theme
• cssresource - any resources referenced by the CSS e.g. images
• html - bundled HTML templates
• i18n - contianing a .js file for each supported application locate
• js - Various JavaScript bundles that can be generated by the Closure Compiler. By default only simple concatenation will occur.

Here are some examples of building and deploying BRJS static apps:

Deploy to Divshot

Divshot focus on offering static hosting for developers.

You'll need a Divshot account, have the CLI installed and have authenticated the CLI. Once you do you can deploy a BRJS app to Divshot as follows:

Make a directory inside your app directory where the app is going to be built to and navigate into it:

› mkdir public
› cd public

Build the app:

› ./brjs build-app brjsapp public

Create a new Divshot app and answer all the questions ensuring that the current (public) directory is chosen as the app directory:

› divshot init

Deploy the app:

› divshot deploy

And finally view the deployed app in your web browser:

› divshot open development

Deploy to GitHub Pages

GitHub offers amazingly simple and powerful static file hosting via GitHub pages.

Assuming git installed, you have a GitHub account and you've got an origin remote set up to point to a GitHub repo you can deploy a BRJS app to GitHub pages as follows:

Make a directory inside your app directory where the app is going to be built to:

› mkdir public

Build the app:

› ./brjs build-app brjsapp public

Add and commit the built app:

› git add public && git commit -m "Initial public subtree commit"

Use subtree push to send it to the gh-pages branch on GitHub.

› git subtree push --prefix public origin gh-pages

Note: this process is based on Deploying a subfolder to GitHub Pages

Deploy to Firebase Hosting

Firebase is a real-time data synchronisation service that also offers production-grade hosting for developers.

First, make sure you've a Firebase account, Node.js installed and have the Firebase Tools installed,

You can now create an application within Firebase via their web app and then initialise the app locally in the directory that that you built your BRJS app in. You may be prompted for your Firebase credentials:

› firebase init brjsapp

Build your BRJS app to the directory:

› ./brjs build-app brjstodo ~/app/brjsapp

Deploy to Firebase hosting:

› firebase deploy

View your deployed app in your web browser:

› firebase open

Build as WAR

If you are deploying to an environment that supports WAR file then BRJS provides support for building a deployable WAR. This is achieved using the -w flag:

./brjs build-app -w myapp ~/brjs-apps

Note: in the above example ~/brjs-apps must exist

This will create a myapp.war file in ~/brjs-apps. You can now deploy the .war file to your WAR supporting web server. For example, deploying to Tomcat is a simple as copying the generated WAR file to the Tomcat webapps directory

Where next?

Localization has been mentioned in this section. You can find out more in the Interationalizing your app section of the docs.