backpack-js v0.0.6

backpack

backpack.js (backpack-js, Backpack, backpack) is a Node.js module to allow users to create custom builds of your project from your website. Backpack is designed to run on a Node.js server deployment, and listens for a custom build selection to be requested, assembles it, and pushes it back to the client in .ZIP form.

$ npm install backpack-js --save-dev

Why backpack?

If you have a highly modular or module orientated project, it may be the case that users may only require a subset of modules. As such, it is more efficient to offer them a build only comprising of what they need, instead of a complete code dump.

Backpack automates the process of users selecting the modules they want and getting a customised build. This means users can simply browse to your site, check some boxes and voila! Have a zip file containing exactly what they need.

Backpack allows:

• Seamless client integration
• Multiple instances of the same script to be referenced between modules, and only included once in the final build
• Multiple scripts across multiple modules to be automatically bundled together into the same file
• Easy definition of unique project structures for different modules

How to use

Backpack Configuration (backpack.json)

You will need to create a backpack.json file in your project directory. This file contains all settings related to your project's modules, and how to conduct a customised build. An example can be found in examples\backpack.json, the structure is e.g.:

{
    "url": "/backpack",
	"method":"POST",
    "modules": [
        {
            "name": "module1",
            "src": [
                {
                    "src": "location/of/a/script.js",
                    "dest": "javascript.js"
                }
            ]
        }
	]
}

####url ######(string) optional, defaults to /backpack

This is the URL backpack will listen to in order to trigger a custom build.

####method ######(string) optional, defaults to POST

Either POST or GET. In conjunction with the URL, backpack will also check if the correct request method is being used (in case you want to use GET to serve the custom build page, and POST with the same URL to trigger it).

####modules ######(array) required

Array of module definitions, here you set your module mappings, related assets and bundling.

####modules/name ######(string) required

Name of the module, this is mapped to incoming requests to determine which modules are included in a build.

####modules/src ######(array) required

List of files which constitute the module

####modules/src/src ######(string)

Path to file

####modules/src/dest ######(string) optional, defaults to src value

Path/name to give the output file within the custom build. It is important to note that you can give multiple src entries accross different modules the same dest entry. Where two or more files are given the same dest, they are bundled together into a single file.

Server Configuration

Assuming you have a node based server already set up, you will need to require backpack, then simply add backpack(request, response) within you http.createServer function, where request and response are the respective objects passed through that function.

An example of this can be found in examples\server.js

This will ensure backpack is listening to requests made from the client, and will pick up and respond to only those relating to a custom build request.

Client Configuration

To launch a new custom build, you will need to create a request which matches the url and method in your backpack.json. At the simplest level, this would constitute an HTML form which POSTs data to /backpack

Backpack looks for the variable backpack in the request, representing an array of modules mapped to entries in backpack.json. An example form may look like (also see example/index.html):

   <form method="post" action="backpack">
      <h1>Available Modules</h1>
      <label>Module 1
      <input type="checkbox" name="backpack[]" value="module1"/>
      </label>
      <label>Module 2
      <input type="checkbox" name="backpack[]" value="module2" />
      </label>
      <label>Module 3
      <input type="checkbox" name="backpack[]" value="module3"/>
      </label>
      <input type="submit"  id="submit" value="Build!" />
   </form>

Here, module1, module2 etc relate to module name values in backpack.json. Backpack finds the correct module entry, then creates a build based on the src definitions of that module.

backpack, written by SW4