Feature highlights
- Minify and concatenate JS and CSS for fast page loads
- Tag rendering
- Namespaces
- Transparent preprocessor
- Push CSS changes to the browser using Socket.IO
- Easy code sharing with server
Piler allows you to manage all your JavaScript and CSS assets cleanly and directly from code. It will concatenate and minify them in production and it takes care of rendering the tags. The idea is to make your pages load as quickly as possible.
So why create a yet another asset manager? Because Node.js is special. In Node.js a JavaScript asset isn't just a pile of bits that are sent to the browser. It's code. It's code that can be also used in the server and I think that it's the job of asset managers to help with it. So in Piler you can take code directly from your Javascript objects, not just from JavaScript files. Copying things from Rails is just not enough. This is just a one reason why Piler was created.
Server-side code:
clientjs.addOb({BROWSER_GLOBAL: {
aFunction: function() {
console.log("Hello I'm in the browser also. Here I have", window, "and other friends");
}
}});You can also tell Piler to directly execute some function in the browser:
clientjs.addExec(function() {
BROWSER_GLOBAL.aFunction();
alert("Hello" + window.navigator.appVersion);
});Currently Piler works only with Express, but other frameworks are planned as well.
Piler is written following principles in mind:
- Creating best possible production setup for assets should be as easy as including script/link to a page.
- Namespaces. You don't want to serve huge blob of admin view code for all anonymous users.
- Support any JS- or CSS-files. No need to create special structure for your assets. Just include your jQueries or whatever.
- Preprocessor languages are first class citizens. Eg. Just change the file extension to .coffee to use CoffeeScript. That's it. No need to worry about compiled files.
- Use heavy caching. Browser caches are killed automatically using the hash sum of the assets.
- Awesome development mode. Build-in support for pushing CSS changes to browsr using Socket.IO.
Full example Express 2.x
var createServer = require("express").createServer;
var piler = require("piler");
var app = createServer();
var clientjs = piler.createJSManager();
var clientcss = piler.createCSSManager();
app.configure(function() {
clientjs.bind(app);
clientcss.bind(app);
clientcss.addFile(__dirname + "/style.css");
clientjs.addUrl("http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.js");
clientjs.addFile(__dirname + "/client/hello.js");
});
app.configure("development", function() {
clientjs.liveUpdate(clientcss);
});
clientjs.addOb({ VERSION: "1.0.0" });
clientjs.addExec(function() {
alert("Hello browser" + window.navigator.appVersion);
});
app.get("/", function(req, res){
res.render("index.jade", {
layout: false,
js: clientjs.renderTags(),
css: clientcss.renderTags()
});
});
app.listen(8080);Full example Express 3.x
var express = require('express'),
http = require('http'),
piler = require("piler"),
app = express();
var clientjs = piler.createJSManager();
var clientcss = piler.createCSSManager();
var srv = require('http').createServer(app);
app.configure(function(){
clientjs.bind(app,srv);
clientcss.bind(app,srv);
clientcss.addFile(__dirname + "/style.css");
clientjs.addUrl("http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.js");
clientjs.addFile(__dirname + "/client/hello.js");
});
app.configure("development", function() {
clientjs.liveUpdate(clientcss);
});
clientjs.addOb({ VERSION: "1.0.0" });
clientjs.addExec(function() {
alert("Hello browser" + window.navigator.appVersion);
});
app.get("/", function(req, res){
res.render("index.jade", {
layout: false,
js: clientjs.renderTags(),
css: clientcss.renderTags()
});
});
srv.listen(8080);index.jade:
!!! 5
html
head
!{css}
!{js}
body
h1 Hello PilerThe example above uses just a one pile. The global pile.
If you for example want to add big editor files only for administration pages you can create a pile for it:
clientjs.addFile("admin", __dirname + "/editor.js");
clientjs.addFile("admin", __dirname + "/editor.extension.js");This will add file editor.js and editor.extension.js to a admin pile. Now you can add that to your admin pages by using giving it as parameter for renderTags.
js.renderTags("admin");This will render script-tags for the global pile and the admin-pile. js.renderTags and css.renderTags can take variable amount of arguments. Use js.renderTags("pile1", "pile2", ....) to render multiple namespaces
Piling works just the same with css.
Ok, that's pretty much what every asset manager does, but with Piler you can share code directly from your server code.
Let's say that you want to share a email-validating function with a server and the client
function isEmail(s) {
return !! s.match(/.\w+@\w+\.\w/);
}You can share it with addOb -method:
clientjs.addOb({MY: {
isEmail: isEmail
}
});Now on the client you can find the isEmail-function from MY.isEmail.
addOb takes an object which will be merged to global window-object on the client. So be careful when choosing the keys. The object can be almost any JavaScript object. It will be serialized and sent to the browser. Few caveats:
- No circural references
- Functions will be serialized using Function.prototype.toString. So closures won't transferred to the client!
This is nothing specific to Piler, but this is a nice pattern which can be used to share modules between the server and the client.
share.js
(function(exports){
exports.test = function(){
return 'This is a function from shared module';
};
}(typeof exports === 'undefined' ? this.share = {} : exports));In Node.js you can use it by just requiring it as any other module
var share = require("./share.js");and you can share it the client using addFile:
clientjs.addFile(__dirname + "./share.js");Now you can use it in both as you would expect
share.test();You can read more about the pattern from here
Sometimes it is nessesary to control pilers output based on the system environment your running your application in. In default mode Pilers logger will output any information it has by using the "console" javascript object. The following example shows how to configure a custom logger
The basic logger facility implements the following methods.
exports.debug = console.debug
exports.notice = console.log
exports.info = console.info
exports.warn = console.warn
exports.warning = console.warn
exports.error = console.error
exports.critical = console.errorThe following example injects "winston", a multi-transport async logging library into pilers logging mechanism.
var piler = require('piler');
var logger = require('winston');
// [More logger configuration can take place here]
global.js = js = piler.createJSManager({ outputDirectory: assetTmpDir , "logger": logger});
global.css = css = piler.createCSSManager({ outputDirectory: assetTmpDir, "logger": logger});More information about winston can be found here.
Development and production modes works as in Express. By default the development mode is active. To activate production mode set NODE_ENV environment variable to production.
This is really cool! You don't want to edit CSS at all without this after you try it!
Because Piler handles the script-tag rendering it can add some development tools when in development mode.
Using Express you can add Live CSS editing in development mode:
app.configure("development", function() {
clientjs.liveUpdate(clientcss);
});This is similar to Live.js, but it does not use polling. It will add Socket.IO which will push the CSS-changes to your browser as you edit them.
If your app already uses Socket.IO you need to add the io-object as second parameter to liveUpdate:
var io = require('socket.io').listen(app);
clientjs.liveUpdate(clientcss, io);In development mode every JS- and CSS-file will be rendered as a separate tag.
For example js.renderTags("admin") will render
clientjs.addFile(__dirname + "/helpers.js");
clientjs.addFile("admin", __dirname + "/editor.js");
clientjs.addFile("admin", __dirname + "/editor.extension.js");to
<script type="text/javascript" src="/pile/dev/_global/1710d-helpers.js?v=1317298508710" ></script>
<script type="text/javascript" src="/pile/dev/admin/3718d-editor.js?v=1317298508714" ></script>
<script type="text/javascript" src="/pile/dev/admin/1411d-editor.extension.js?v=1317298508716" ></script>in development mode, but in production it will render to
<script type="text/javascript" src="/pile/min/_global.js?v=f1d27a8d9b92447439f6ebd5ef8f7ea9d25bc41c" ></script>
<script type="text/javascript" src="/pile/min/admin.js?v=2d730ac54f9e63e1a7e99cd669861bda33905365" ></script>So debugging should be as easy as directly using script-tags. Line numbers will match your real files in the filesystem. No need to debug huge Javascript bundle!
Visit this directory to see a simple example using ExpressJS 2.x.
This example uses ExpressJS 3.x a custom logger (winston) and a global socket.io instance together with Piler.
Code will be rendered in the order you call these functions with the exception of addUrl which will be rendered as first.
Can take an optional configuration object as an argument with following keys.
var jsclient = piler.createJSManager({
outputDirectory: __dirname + "/mydir",
urlRoot: "/my/root"
});
Url root to which Piler's paths are appended. For example urlRoot "/my/root" will result in following script tag:
<script type="text/javascript" src="/my/root/min/code.js?v=f4ec8d2b2be16a4ae8743039c53a1a2c31e50570" ></script>
If specified Piler will write the minified assets to this folder. Useful if you want to share you assets from Apache etc. instead of directly serving from Piler's Connect middleware.
File on filesystem.
Useful for CDNs and for dynamic assets in other libraries such as socket.io.
Keys of the object will be added to the global window object. So take care when choosing those. Also remember that parent scope of functions will be lost.
You can also give a nested namespace for it
clientjs.addOb({"foo.bar": "my thing"});
Now on the client "my thing" string will be found from window.foo.bar.
The object will be serialized at the second it is passed to this method so you won't be able modify it other than between server restarts. This is usefull for sharing utility functions etc.
Use res.addOb to share more dynamically objects.
A function that will executed immediately in browser as it is parsed. Parent scope is also lost here.
Any valid Javascript string.
These are similar to ones in JS pile.
CSS asset on your filesystem.
CSS asset behind a url. Can be remote too. This will be directly linked to you page. Use addFile if you want it be minified.
Any valid CSS string.
For JavaScript the only supported one is CoffeeScript and the compiler is included in Piler.
CSS-compilers are not included in Piler. Just install what you need using npm.
Adding support for new compilers should be easy.
Feel free to contribute!
From npm
npm install piler
Source code is licenced under The MIT License and it is hosted on Github.
v0.4.2 - 2013-04-16
- Fixes to work with ExpressJS 3.x
- Unit test fixes
- Make console output configurable
v0.4.1 - 2012-06-12
- Add getSources
- Put cache key to resource url instead of query string
v0.4.0 - 2012-06-17
- Remove Dynamic Helpers.
Dynamic Helpers where an Express 2.0 only API. This makes Piler more framework agnostic and it will work with Express 3.0. This also removes support for response object functions. We'll add those back if there is a need for them (open up a issue if you miss them!) and we'll find good framework agnostic way to implement them.
v0.3.6 - 2012-06-17
- Bind all production dependency versions
v0.3.5 - 2012-06-17
- Fix LESS @imports
- Fix Stylus without nib
- Use path module for Windows compatibility
v0.3.4 - 2012-03-29
- Fix Stylus @imports
v0.3.3 - noop
v0.3.2 - 2011-12-11
- Workaround compiler bug in CoffeeScript
v0.3.1 - 2011-11-17
- Fix CSS namespaces
v0.3.0 - 2011-10-13
- Rename to Piler
- Really minify CSS
- Implemented res.addOb
- Implement outputDirectory and urlRoot options.
- addOb can now take nested namespace string and it won't override existing namespaces.
Questions and suggestions are very welcome
- Esa-Matti Suuronen
- esa-matti [aet] suuronen dot org
- EsaMatti @ Twitter
- Epeli @ freenode/IRCnet