qthru / node-server-config

Express / Connect middleware for websites. Goes well with HTML5 Boilerplate.

H5BP

HTML5 boilerplate (H5BP) server config for node.js.

h5bp for node.js follows the guidelines of the Apache version:

• secures backup and hidden files.
• optionally redirects www.yoursite.tld to yoursite.tld or yoursite.tld to www.yoursite.tld.
• offers a simple cache busting mechanism.
• normalize content types.
• optionally enables CORS.
• sets correct cache expires depending of the type of resource.
• and some others...

It also focuses on offering additional features such as on-the-fly script concatenation using CommonJS or AMD.

Next release focus (v0.0.7)

• grunt style scripts and stylesheets concatenation.
• on-the-fly scripts minification.
• on-the-fly LESS and SASS compilation.
• development mode: always refresh on-the-fly generated resources.

Installation

npm install h5bp

Quick Start

Create a simple http server

var h5bp = require('h5bp');

var app = h5bp.createServer({ root: __dirname + '/public' });
app.listen(3000);

app is an instance of an express application. You can add additional middlewares or routes if you like.

Use it as a connect / express middleware

var express = require('express'),
    h5bp = require('h5bp');

var app = express();
app.use(h5bp({ root: __dirname + '/public' }));

// in order to serve files, you should add the two following middlewares
app.use(express.compress());
app.use(express.static(__dirname + '/public'));
app.listen(3000);

Concatenate scripts on-the-fly

If you want to split your application source files but only serve one file, you can use the on-the-fly concatenation. If you are familiar with node.js, you can use the CommonJS style. You can also use the AMD style.

app.use(h5bp({
    root: __dirname + '/public',
    scripts: {
        files: ['app.js'],
        processor: 'commonjs'   // can also be "amd"
    }
}));

At the first request hit to /app.js, the server will compile, cache and serve the file. Any subsequent request will serve the cached file without any performance impact.

So, this feature is meant to be used with the cache busting mechanism in order to ensure the client always has the latest resource version. If you restart your server, the cache will be flushed.

Note that the next release will provide a development mode where the server will simply disable its cache and always serve the latest version of the file.

Options

There are several options you can pass to the middleware.

app.use(h5bp(options));

root

Tells the filesystem path to the root directory of static resources. This options is mandatory if you serve static files.

www

Forces www if true, forces non-www if false, does nothing if not defined. By default, this is disabled.

cors

Enables CORS for everything. By default this is disabled.

scripts

Tells which scripts to concatenate.

This is an object with the following properties:

files

This is an array of files to concatenate. Their path is relative to the root option. Their URL will be absolute.

For example, if you set files to ['scripts/app.js'] and root to /home/h5bp/app/:

• The path will be: /home/h5bp/app/scripts/app.js.
• The served URL will be: yoursite.tld/scripts/app.js.

processor

Tells which processor to use for scripts concatenation.

For now, it can be one of the following values:

• commonjs: will concatenate files using the CommonJS method (require/exports).
• amd: will concatenate files using the AMD method (require/define).

Additional options

The h5bp.createServer function takes the same options, plus additional ones.

The callback is optional. It is a custom middleware that you can register directly if you want to.

h5bp.createServer(options, [callback]);

server

Tells which type of server you want to use.

It can be one of the following values:

• express: uses express, this is the default value.
• connect: uses connect.

logger

Tells if you want to log server requests or not. This can also be an object containing logger options.

compress

Tells if you want to serve gzipped content or not. By default this is true.

If you are using h5bp as a middleware, we strongly encourage you to use the compress middleware provided by express / connect.

Contributors

 project  : node-server-config
 repo age : 2 years, 2 months
 active   : 55 days
 commits  : 98
 files    : 73
 authors  : 
    42	Nicolas Gryman          42,9%
    17	xonecas                 17,3%
     9	Nick Baugh              9,2%
     8	Sean Caetano Martin     8,2%
     5	Benjamin Tan            5,1%
     3	Clemens Stolle          3,1%
     3	sean                    3,1%
     2	AD7six                  2,0%
     2	Dean Gelber             2,0%
     2	alrra                   2,0%
     1	Przemek Matylla         1,0%
     1	David Murdoch           1,0%
     1	Mike Almond             1,0%
     1	Nicolas Gallagher       1,0%
     1	Chad Smith              1,0%

How to contribute?

If you want to contribute for a bug or an enhancement, please do it on master. master is our stable branch where releases and fixes land.

If you want to contribute for a new feature, please do it on develop. develop is our mainline where the next release is prepared.

Here is the workflow overview:

• Fork the repository.
• Clone it.
• Checkout the right branch.
• Add your awesome contribution.
• Test!
• Push to Github.
• Open a pull request to the right branch.

Always run tests

This project tries to be as test driven as possible. So your contribution should always be covered by associated functional test(s). This ensure that what you are actually adding work as expected and do not break anything. We use Mocha to run the tests and Chai as the assertion library.

Before pushing anything to Github, please ensure that all tests are passing.

From the root of the project you can run tests like this:

npm test

Keeping your repo in sync

Please rebase instead of merging. This is just to avoid having a lot of merge commits polluting the history of the project.

# this adds our repo as another remote, only the first time
git remote add h5bp git://github.com/whoever/whatever.git

# fetches all branches from h5bp repo, only the first time
git fetch h5bp

# make sure your have checkout the right branch
git checkout [master|develop]

# rebase h5bp/master
git rebase h5bp/master

If you are not confortable with rebasing, please take a look at http://git-scm.com/book/en/Git-Branching-Rebasing or ask us some help :)

Squash your commits

At the end of your pull request review, you may have several commits in it. Please squash all your commits into one with a clear message. This is to have a clear history in the project when each commit is relevent to a feature, enhancement or bug.

If you are not confortable with squashing commits, please take a look at http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html or ask us some help again :)

Thanks!