This guide will introduce you to Shunter and teach you how to use it to put together a basic application. More advanced documentation is also available if you need more detail.
This guide will not explain every feature of Shunter. Its aim is to get you up-and-running in as little time as possible.
Looking to create a smart, flexible, robust, loosely-coupled front end?
Need a hand defining integration points between your front and back end applications?
Want to use the same unified front end across both your Rails/PHP/ASP/other application, and your Wordpress-driven blog?
Shunter is for you.
Technically speaking Shunter runs your loosely-coupled front end as a node.js server, acting as a reverse proxy in front of your back end application(s). This can be deployed on the same or a different server from your other applications as you see fit (it's super lightweight).
When a request comes in from a client, it's proxied through to your back end application (or can use multiple back ends using some simple routing logic). Any JSON response that is sent back with the special response header (by default Content-Type application/x-shunter+json) will be taken by Shunter and transformed using Dust.js, while any other resource is transparently passed back through to the client.
Before we begin, you'll need to have Node.js installed. Shunter requires Node.js 4.x–6.x.
You'll need to be comfortable with the command line, and have some basic knowledge of HTML, CSS, JavaScript, and templating.
We'll start by creating a package.json file in a new directory. We're just including Shunter for now:
{
"name": "getting-started-with-shunter",
"version": "1.0.0",
"main": "app.js",
"dependencies": {
"shunter": "*"
}
}(Please note: you should set a specific version of Shunter when preparing a real-world application.)
Now we can run npm install to install dependencies. Once the dependencies have installed, we'll start to flesh out our application.
Shunter has a configurable directory structure. For now, we'll use the defaults. Run the following:
mkdir -p data public resources/css resources/img resources/js viewThis should create the following directories:
├── data
├── public
├── resources
│ ├── css
│ ├── img
│ └── js
└── view
Now we need to write the application itself. This is nice and simple; add the following to a new file named app.js:
// Require in Shunter
var shunter = require('shunter');
// Create a Shunter application, passing in options
var app = shunter({
// Configure the proxy route, this should point to
// where your back end application runs
routes: {
localhost: {
default: {
host: '127.0.0.1',
port: 5401
}
}
}
});
// Start the application
app.start();When we run this file using node app.js, you should see a short delay then a message like this:
Shunter started with X child processes listening
If you open up http://localhost:5400/ in your browser, you should see a blank page in your browser and get some error messages in your terminal window. That's because we haven't got a back end running yet.
For the purposes of testing, Shunter comes bundled with a simple application for serving static JSON files. This allows you to create a mock back end application which your Shunter application can connect to.
In a new terminal window, run the following to start a sample back end:
./node_modules/.bin/shunter-serveYou should see a message like this:
JSON server listening on port 5401
Leave this running. Now if you re-run node app.js in your original terminal window and visit http://localhost:5400/ you should see a nice page with some form fields!
We'll want to provide a sample JSON file that the Shunter application can proxy to. We create sample JSON files in the data folder. Add the following to data/home.json:
{
"layout": {
"template": "home"
},
"title": "Hello World!",
"list": [
"foo",
"bar",
"baz"
]
}Notice the layout.template property in the JSON we just created? That indicates the Dust template that should be used to render the page.
Also worthy of note is that the layout object in the root, with the template property, is the only thing Shunter requires in the JSON response.
Anyway, if we open up http://localhost:5400/home now, then you'll see an error in your terminal indicating that the "home" template can't be found…
Let's create that missing "home" template. Add the following to view/home.dust:
<!DOCTYPE html>
<html>
<head>
<title>{title}</title>
</head>
<body>
<h1>{title}</h1>
<p>Welcome to your first Shunter page!</p>
</body>
</html>Note our use of {title}. This is a reference to the title property in our JSON file.
Now restart your Shunter application again and open up http://localhost:5400/home in your browser. You should see your rendered page.
Dust templating is very powerful, right now we're using the absolute basics. But we can add a basic Dust loop using the following:
<ul>
{#list}
<li>{.}</li>
{/list}
</ul>Dust will render:
<ul>
<li>foo</li>
<li>bar</li>
<li>baz</li>
</ul>Once you've finished this guide, you can learn more about layouts and partials.
Next we'll add some styles.
Shunter's resources are managed through Mincer, which adds in asset fingerprinting, concatenation, and minification.
CSS and JavaScript files in Shunter are actually run through the EJS templating language which gives us some useful helpers. These will come into play when we're adding a stylesheet.
Add the following to resources/css/main.css.ejs:
body {
font-family: Arial, Helvetica, sans-serif;
text-align: center;
color: #004f8b;
background-color: #e0f1ff;
}We'll also need to link to our stylesheet from view/home.dust:
<link rel="stylesheet" href="{@assetPath src="main.css"/}"/>Notice the assetPath helper we used? This is required for Shunter to load the MD5-fingerprinted file. If you don't add this, assets will load in development mode but not in production. You can read more about the assetPath helper here.
Now refresh your page in-browser. Your page should be a lovely shade of blue!
Add the following to resources/js/main.js.ejs:
document.body.style.backgroundColor = randomValue([
'#fadbd1',
'#e1f3c8',
'#b6dff2'
]);
function randomValue(array) {
return array[randomBetween(0, array.length - 1)];
};
function randomBetween(min, max) {
return Math.floor(Math.random() * (max - min + 1)) + min;
};Then load the JavaScript into view/home.dust by adding the following just before the closing </body>:
<script src="{@assetPath src="main.js"/}"></script>Note that we're using the assetPath helper again.
Now refresh your page in-browser and see what happens. The body background should change on page load.
You've successfully created your first Shunter application! You've learned:
- Basic application structure
- Using sample data
- Building views
- Writing and loading CSS
- Writing and loading JavaScript
As a next step you can read up on the rest of the usage documentation and options, or continue to tweak your new application.