File System Packager
JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
test
Makefile
README.md
main.js
package.json

README.md

fspkg: File System Packager

fspkg takes a directory or file as input and transforms it into a CommonJS module, JSON string or JavaScript object. fspkg is great for:

  • bundling mustache templates for inclusion in a client-side application.
  • encoding images and other assets as Data URIs.

For example, I use fspkg with modulr-node to compile my mustache templates for use in a backbone.js application. This lets me do this within my backbone views (assuming I've packaged up my "views" directory:

var MyView = Backbone.View.extend({
    ...
    render: function() {
      var template = require('views')['layouts/index.mustache'];
      var html = Mustache.to_html(template, this.model);
      this.el.html(html);
    },
    ...
});

Command-line API

Usage: fspkg [options] <source>

  Options:

    -h, --help                     output usage information
    -V, --version                  output the version number
    -s, --save-path [savePath]     save path: prints to stdout if not given
    -e, --extensions [extensions]  file extensions to include in the package; default is "mustache,html,htm,txt"

Node.js API

fspkg exposes both async and sync API's.

Main Function

The module export is a shortcut to instantiating a new Builder and immediately its build method, packaging the file-system at path.

fspkg(path, [options,] cb)
- path (String): Path to the file to package.
- options (Object): Options to configure the builder.
- cb (Function(e, content)): Callback function which is given the file content.

Example

require('fspkg')('./views', function(e, pkg) {
  console.log(pkg);
});

The above example would print a CommonJS module similar to this:

module.exports = {
  "index.mustache": "<div>\n  Welcome {{username}}!\n</div> ...",
  "about/index.mustache": "<h1>This {{expletive}} is awesome</h1> ...",
  "about/contact.mustache": "<h1>Contact Us</h1>\n Phone: {{phone}}..."
  // etc...
}

Builder (async)

new Builder([options])
- options (Object): Options to configure the builder.

Creates a new Builder instance. Available Options:

  * filter (Function|String): A function or string which filters file paths
    found in the directory to be packaged.
    
    If a `String`, it should be a comma-separated list of file extensions,
    such as "foo,bar,baz". If a `Function`, should return `true` to include
    the file, `false` to exclude it.
    
    Defaults to "mustache,html,htm,txt".

  * format (String): The format to return from the `build` method:
    "module", "json" or "object". Defaults to "module";



Builder#build(path, cb)
- path (String): The root path of the package.
- cb (Function(e, result)): Callback function which is given the result.

Builds the directory or file `path`. `result` is a package in the configured format.



Builder.Processor.*(path, cb) -> String
- path (String): Path to the file to package.
- cb (Function(e, content)): Callback function which is given the file content.

All processors have the same signature: they take a file path and callback function.
The file content is encoded file as a String and passed to `cb` as the 2nd argument.

Builder.Processor.Default(path, cb)
Builder.Processor.Base64(path, cb)
Builder.Processor.DataURI(path, cb)

SyncBuilder

new SyncBuilder([options])
- options (Object): Options to configure the builder.

Creates a new SyncBuilder instance. Available Options:

  * filter (Function|String): A function or string which filters file paths
    found in the directory to be packaged.
    
    If a `String`, it should be a comma-separated list of file extensions,
    such as "foo,bar,baz". If a `Function`, should return `true` to include
    the file, `false` to exclude it.
    
    Defaults to "mustache,html,htm,txt".

  * format (String): The format to return from the `build` method:
    "module", "json" or "object". Defaults to "module";



SyncBuilder#build(path) -> ?
- path (String): The root path of the package.

Builds the directory or file `path`, returning a package in the configured format.



SyncBuilder.Processor.*(path) -> String
- path (String): Path to the file to package.

All processors have the same signature: they take a file path and return the
encoded file as a String.

SyncBuilder.Processor.Default(path) -> UTF-8 encoded string.
SyncBuilder.Processor.Base64(path) -> Base64 encoded string.
SyncBuilder.Processor.DataURI(path) -> Base64 encoded Data URI.

Filter

Filter.Default(path) -> Boolean
- path (String): The path to the file.

Returns `true` if the file should be included in the package, otherwise: `false`.
Only .mustache, .html, .htm and .txt files pass this filter, and all files within
".git" and "node_modules" direcotories are excluded.

Example

var fs = require('fs');
var fspkg = require('fspkg');

var builder = new fspkg.SyncBuilder({
  filter: function(path) {
    // Include .png files...
    if (path && path.match(/\.png$/)) return true;
    return fspkg.Filter.Default(path);
  },
      
  // Use the Data URI processor for .png files
  '.png': function(path) {
    return fspkg.SyncBuilder.Processor.DataURI(path);
  }
});

// Assuming you have a "stuff" directory with PNGs and other
// files that you want to package up:
var result = builder.build('./stuff');

// Write the module to the current directory as "assets.js".
fs.writeFileSync('./assets.js', result);

// Now you can require() the file and use it for whatever.
console.log(require('./assets.js'));

Install

npm install fspkg

To install the command-line utility, add the -g flag during installation.

License

MIT