Zug

Abstracts away boilerplate code for your express apps.

Note: Upgrading from Zug v0.3.x to v0.4.x will upgrade your app from express 3 to express 4.

This should work without any changes to your code if you don't use any express 3 specific code in your app.

Quick Start Guide

Minimal:

require('zug')([ { http:8080 } ]);

All modules:

require('zug')([
  'static', 'gzip', 'cache', 'jade', 'stylus', 'csrf', 'fileupload',
  { session: 'redis' },
  { multilang: ['en', 'es', 'de'] },
  { mysql: { user:'username', password:'password', db:'database' } },
  { http: { port:8080, host:'1.2.3.4' } },
  { https: {
    certFile:'./ssl/server.cert',
    keyFile:'./ssl/server.key',
    caFile:'./ssl/ca.cert'
  }}
]);

Example:

require('zug')([
  'session', 'gzip', 'cache', 'jade', 'stylus',
  { http:8080 }
]);
 
app.get('/', app.page('home'));

(app.page(view, locals) -> res.render(view, locals))

Without using globals:

var zug=require('zug')([
  'session', 'static', 'gzip', 'cache', 'jade', 'stylus',
  { http:8080 }
]), app=zug.app;
 
app.get('/', app.page('home'));

Directory structure

./css/            Stylus source folder (.styl)
./views/          Views (.jade)
./static/         Public directory
./static/css/     Stylus destination folder (changes will be overwritten!!)
./static/js/      Client side javascript (optional)
./static/img/     Images (optional)
./app.js          Main application file

Dependencies

If you add any zug module that requires a npm package, zug will update an existing or create a new package.json. Just run npm install after being told to to install all required packages.

Helper functions

app.page(view [, locals])

app.page('view', {foo:1}) returns function(req, res) { res.render('view', {foo:1}); }

zug.getToken([length=32])

Generates a random token like Mw6VasisNDGf9jd18634kwC6qZwWA882.

zug.mkdirIfNotExists(dir)

Creates a directory if it does not exist.

zug.getHash(arg [, arg ...])

Returns a base64 encoded sha256 hash of all arguments.

Modules

cache

Sets caching headers for images, stylesheets, scripts and fonts.

csrf

Information:

Provides app.csrf middleware and csrf local variable in views.

Include csrf into a page, pass the value within all Ajax requests and check it server side using app.csrf middleware.

app.post('*', app.csrf); will protect all POST requests.

Depends on:

• session

Example:

require('zug')([
  'jade', 'session', 'csrf',
  { http: { port:8080 } }
]);
 
app.post('/test', app.csrf, function(req, res) {
  res.json({hello:'world'});
});

doctype
html
  body(data-csrf=csrf)
    script(src="://code.jquery.com/jquery-1.10.1.min.js")
    script.
      $.post('/test', {
        csrf: $('body').attr('data-csrf')
      }, function(res) {
        console.log(res);
      }).error(function(err) {
        alert('Error!');
      });

fileupload

Information:

Provides app.fileUpload middleware.

Required npm packages:

• connect-multiparty

Example:

app.post('/upload', app.fileUpload, function(req, res) {
  console.log(req.files);
});

gzip

Enables gzip compression.

http

Options:

• port: Port number
• host: Hostname

or just the port number:

 { http:8080 }

https

Options:

• keyFile
• certFile
• caFile (optional)
• requestCert (optional, default: false)
• port (optional, default: 443)

Example:

require('zug')([
  { https: {
    certFile:'./ssl/server.cert',
    keyFile:'./ssl/server.key',
    caFile:'./ssl/ca.cert'
  }}
]);

jade

Information:

Create your views in ./views/.

Required npm packages:

• jade

multilang

*** TBD ***

mysql

Options:

• user: MySQL user name
• password: Password
• db: Database name

Information:

Provides global sql and zug.sql.

Required npm packages:

• mysql

Example:

require('zug')([
  { mysql: { user:'username', password:'password', db:'database' } },
  { http:8080 }
]);
 
app.get('/', function(req, res) {
  sql.query(
    'SELECT * FROM table WHERE ID=?',
    [1337],
    function(err, rs) {
      res.render('page', {data:rs});
    }
  );
});

namespace

Information:

Provides namespace capabilities. *** Deprecated: *** Use express 4 routes instead!

Example:

app.namespace('/test', function(app) {
 
  app.get('/', function(req, res) {
    res.end('URL: /test/');
  });
 
  app.get('/foo', function(req, res) {
    res.end('URL: /test/foo');
  });
 
});

session

Options:

• store: 'redis' or 'memory' (default)
• redis: settings object for redis connection

or just a string:

 { session:'redis' }

Information:

Provides req.session. Generates a session.key file containing the session secret if it does not exist.

Required npm packages:

• connect-redis (if you are using redis store)

Example:

require('zug')([
  { session: { store:'redis' } },
  { http:8080 }
]);
 
app.get('/', function(req, res) {
  req.session.count=(req.session.count || 0)+1;
  res.end('Count='+req.session.count);
});

static

Serves static files from ./static/ directory.

stylus

Information:

Create your .styl files in ./css/, they will be compiled to ./static/css/ on-the-fly.

Depends on:

• static

Required npm packages:

• stylus

Tests

npm run install-all to install all required modules.

npm run test to run tests.

npm run test-all to include tests for redis store and mysql.

License

MIT