Open-armed asset compiling for Node.js.
compiln uses a plugin-based architecture to allow YOU to choose your preprocssor stack, not me.
How to install
npm install compiln
How to use
Middleware (Connect or Express):
compiln can be used as middleware. The middleware accepts 3 options:
buildOnStart- Compile assets when the server starts (defaults to "true")
buildOnRequest- Compile an asset every time it is requested (defaults to "false")
version- Version/fingerprint asset filename when compiled (defaults to "true")
var compiln = ;app;
What compiln will compile is dictated by what compiln plugins are being used. To compile CoffeeScript, for instance, simply install the complin CoffeeScript plugin:
npm install compiln-coffeescript
And tell compiln to use the plugin:
var compiln_coffeescript = ;compiln;
use method accepts four total parameters:
- The plugin. (Required)
- The path of the root source folder for that asset type. (Optional)
- The path of the root destination folder for that asset type to be compiled to. (Optional)
- An object of options for the plugin. (Optional)
compiln can also be configured with a json file in the root directory named
These settings will be overwritten by any settings made when integrating the middleware.
"sources" is an array of files that should be compiled by compiln (used by the CLI). Note that the source file name uses the compiled extension (
.js) rather than the preprocessor extension (
compiln has the built in ability to "version" (or "fingerprint") compiled assets. When using versioning, a source file like:
will compile into something like this:
The "version number" is an MD5 tag, and its generation is based off of the file's content. If you were to recompile the exact same file, it would have the exact same version number. This allows you to set the client-side caching of your assets to a very-long/never expiry date. If the file contents change, the client will be automatically requesting a different filename.
compiln includes a method to retrieve the versioned filename of an asset. This is especially useful if you are using a templating language that allows for function calls, like Jade. To inject the versioned filename, simply use the
This will render HTML something like:
compiln has a secondary helper to allow for versioned filename injection into files that don't support helper functions. After compiling a file, compiln will look for all versioned files declared with the following format:
compiln will replace all instances of the above format with a string of the versioned file path.
Whether through template helper functions or keyed string replacement, compiln can easily version your files and ensure that the correct file names are compiled into your code.
One of the benefits of compiln is that it is an open preprocessor compiling platform - it does not specify or dictate which preprocessors to use. If you would like to use compiln to compile an asset type for which a plugin does not exist, then you can easily write a new plugin.
compiln plugins require three methods to be defined. These methods should be made available by adding them to
module.exports.detect- Should return an array of extensions. These are the extensions that the source files possess. The extensions should not include the dot (ie.
module.exports.ext- Should return a string of the destination extension - the extension the source files will compile into. This should not include the dot (ie.
js). If the plugin will compile into the same format as the source file, return
nulland compiln will use the extensions declared in
module.exports.compile- Accepts three parameters:
fileis the source file path.
optionswill contain any options passed when the plugin is passed to compiln.
options.versionedFileis automatically included in all plugin
options- this can be used to pass the
versionedFilehelper to the third-party compiler. The
compilemethod should load the source file (ie. via
fs.readFileSync) and return the compiled data.
The wiki keeps a list of available plugins. If you contribute a plugin, add it to the list so others can find it too.
If you'd rather not use compiln as middleware, compiln includes a CLI to allow you to precompile your assets.
To use, install compiln globally:
npm install -g compiln
To build the files:
-b argument to compile without versioning. To compile specific files, pass the files as a comma-delimitated list with the
Note that the CLI requires
compiln.json in order to utilize plugins and know which files should be compiled.
(The MIT License)
Copyright (c) 2013 Ian Lollar
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.