grand-central-pipeline
v0.1.2
Published
(DEPRECIATED) A javascript asset pipeline for Node
Downloads
5
Maintainers
Readme
DEPRECIATED
Not being updated, for historic preservation only
Grand Central Pipeline
A javascript asset pipeline for Node and Express. Based on the Sprockets/Rails methods for giving directives and concatenating javascript files. Minifies using UglifyJS in production environments.
TODO:
- Client-side debugging
- Examples folder with simple Express app
Documentation
Breaking Changes in 0.0.8
- The
dest
directory is now your main public/assets directory. No need to specify ajavascripts
folder; any requested JS files will havedest
as a base. So requesting/javascripts/app.js
will compile the file in[dest]/javascripts/app.js
from the file[src]/app.js
.
Setup with Express
Grand Central Pipeline can be used as middleware to serve javascript assets from any Express application.
Options that can be specified:
source
( required ) : the directory of the actual javascript files to be compiled.dest
( required ) : the asset directory you want any compiled files to be requested from.minify
(defaultfalse
) : set to true to minify all javascript. If not present, GCP minifies in production and concatenates in development.templateName
(defaultjst
) : the name of the global client-side object that stores all javascript templates.
All options and defaults:
require('grand-central-pipeline')({
source: '', // required
dest: '', // required
minify: false,
templateName: 'jst',
templateDir: '',
env: (current Node Environment || 'development')
});
Example code in your app.js
file or wherever you initialize your Express app:
var express = require('express'),
path = require('path'),
gcp = require('grand-central-pipeline'),
app = express();
app.configure(function(){
app.use(gcp({
source: path.join(__dirname, 'client'),
dest: path.join(__dirname, 'public')
}));
// It's best to put the GCP middleware above Express's static asset pipline:
app.use(express.static(path.join(__dirname, 'public')));
});
All client-side javascript goes in the source directory (/client
in this case). When a file is requested, it is compiled into a single JS file in the public dest directory (/public
in this case). So a request for /javascripts/app.js
will be compiled into the public/javascripts
directory.
Any requests made outside of /javascripts
will not be run through the processor.
Minification
In the development environment, required JS files are concatenated and labeled as is. In production, they are minified using UglifyJS.
Directive Processor
Modeled after Sprockets, GCP is run on every requested javascript file. It scans for comment lines beginning with =
at the top of the file.
Example in client/sample.js
:
//= require lib/jquery
//= require_tree ./ui
/* Multi-line comment
*= require file1 file2 file3
*/
$(function(){ document.write("Hello World") });
This would output to, and be requested from /javascripts/sample.js
, and will include the required files and directories in the order they are listed. Code at the bottom of the file will be at the end of the combined version.
It can be linked to in views as:
<script type="text/javascript" src="/javascripts/sample.js"></script>
If javascripts/folder/sample.js
is requested by the client, the corresponding source file should be in client/folder/sample.js
.
The Directive Processor is recursive, meaning all bundled files are also checked. So if 'models.js' is required, that file will also be checked for any directives and those files will also be bundled.
GCP Directives
require
require
path inserts the contents of the asset source file specified by path. If the file is required multiple times, it will appear in the bundle only once.
include
include
path works like require
, but inserts the contents of the specified source file even if it has already been included or required.
require_directory
or requireDirectory
require_directory
path requires all source files in the directory specified by path. Files are required in alphabetical order.
require_tree
or requireTree
require_tree
path works like require_directory
, but operates recursively to require all files in all subdirectories of the directory specified by path.
Templating
Javascript templating is also supported. GCP supports Embedded Javascript/Underscore (.ejs) and Handlebars (.hbs) templates. Any files required by the requested JS (as in using //= require sample.hbs
) with those extensions will be compiled.
The templates can be accessed through the namespace jst['path/file']
or whatever template name you provide in the options.
So if your template's actual path was client/templates/home/index.ejs the corresponding client-side javascript would be:
var template = jst['templates/home/index'];
$("div").html(template({ JSONDATA }));
Make sure you have the appropriate client-side libraries for templating:
- Underscore.js
- Handlebars runtime library. Each template is also a Handlbars partial with the name
path.file
that can be accessed with{{> path.file}}
. So for the example below, the partial name would belist
.
Template in client/templates/list.hbs, assuming the template (or folder) is required in app.js:
<script type="text/javascript" src="javascripts/handlebars-runtime.js"></script>
<script type="text/javascript" src="javascripts/app.js"></script>
<script type="text/javascript">
var template = jst['templates/list'];
$("#list").html(template({ DATA }));
</script>
Use the option templateDir
if you have a single folder with templates in your source directory. So with the option templateDir: 'templates'
, the file project.hbs
within source/templates
will be called on the client-side with jst['project']
. You still need to //= require_tree ./templates
for this to work.
Command Line Tool
$ gcp [source] [destination] --min --all
source
is the only required argument. The source javascript file will be processed and concatenated into the same directory as `filename.dist.js'.destination
is the destination of the processed file.--min
minifies the javascript.--all
both concatenates and minifies.
Client-side Debugging
[WORK IN PROGRESS] The GCP client-side library handles errors to return the correct file names and line numbers for debugging.
Skipping files
If you don't want a .js
file to be compiled, add _"skip" to the filename. So file_skip.js
will be passed over. This also works for folders, so /files_skip/app.js
and anything in that folder will be skipped.