Norwegian Parcel Mail


    0.5.18 • Public • Published

    spritz: A pretty simple web server framework

    spritz is a really simple framework for dealing with http request/response stuff


    npm install spritz

    Available functions

    • spritz.start(options[, callback]): Starts a new instance of an HTTP server based on the supplied options;

      The available options are:

      • proto: The protocol to use on our server (the currently supported protocols are: http, https, fastcgi) - defaults to http;
      • address: The network address to bind on (either an IP address or a UNIX domain socket patch) - defaults to;
      • port: The port number to bind on - defaults to 8080;
      • processes: The number of processes to pre-fork - defaults to 1;
      • mimes: An object containing the Content-type to use for file each extension - defaults to a builtin pre-initialized list.

      The options are still going to be passed to createServer() so all the node https server options are supported.

    • spritz.use(extension): Loads a certain spritz extension (i.e: middlewares, template engines, custom functions, etc...);

    • spritz.on(routePath|regExp|statusCode|hook[, options], callback): Declares a spritz route or status handler and its callback;

      The first argument can be:

      • A string containing the exact path of the route. I.e.: '/about/';
      • A regular expression containing a pattern for the route. The captured groups will be available via the RegExp object as ususal. I.e.: /^\/articles\/(\d+)/;
      • A status code, in case we want to declare a status handler. I.e.: 404;
      • A hook name, started by the '#' (hash) sign, in case we want to declare a hook handler. Check the hooks section below;

      The available options (for route handlers) are:

      • method - The method on what this route applies to - defaults to GET;
      • dontReadPOSTData: true - To not read the POST data from the request (in case we want to use spritz.proxy() on this request);
      • auth - A basic authentication rule. Check the basic authentication section below.

      The callback will always get (request, response) as arguments.

    • spritz.auth(routePath|regExp, authRule) - Defines an authentication rule for a certain route path or regular expression. Check the basic authentication section below.

    • spritz.text(req, res, text[[, statusCode, [headers], [callback]]]) - Returns a text string as a response for a certain request;

    • spritz.json(req, res, someObject[[, statusCode, [headers], [callback]]]) - Returns the serialized JSON content of an object as a response for a certain request;

    • spritz.staticfile(req, res, filePath[[, statusCode, [headers], [callback]]]) - Returns the content of a file as a response for a certain request;

    • spritz.proxy(req, res, host|url[[, port, [options], [callback]]]) - Proxies the current request to another host or URL;

      The port argument defaults to 80;

      The available options are:

      • proto - The protocol of the request to send to the remote server - defaults to http;
      • method - The method of the request to send to the remote server - defaults to the current request method;
      • path - The path of the request to send to the remote server - defaults to the current request path;
      • headers - The headers of the request to send to the remote request - default to the current request headers;
      • timeout - A request timeout for the request to send to the remote server (in milliseconds);
      • onError - A error handler callback;
      • onTimeout - A timeout handler callback;


    The available hooks are:

    • #setroute - Called when a route is declared (synchronous);
    • #arrive - Right after a request arrives (asynchronous);
    • #readheaders - After the headers of a request are read (asynchronous);
    • #read - After a request is read (asynchronous);
    • #findroute - After finding (or not) the matching route for a request (asynchronous);
    • #beforewritehead - Before writing the headers of a response (asynchronous);
    • #beforewritedata - Bebore writing the content of a response (asynchronous);
    • #beforefinish - Before finishing to handle a request and sending its response (asynchronous);
    • #finish - After finishing to handle a request and sending its response (asynchronous).

    Hooks declared in UPPERCASE (i.e.: #SETROUTE) via spritz.on() will be declared as global and will be used in every spritz server instance.

    Basic authentication

    Basic authentication is supported as a built-in feature. Authentication rules can be specified either via spritz.auth('/some_route', someRule) or spritz.on('/some_route', {auth: someRule}, ...).

    An authentication rule should always contain a realm property and either a username/password pair or a check function which is responsible to verify if the supplied user/pass pair is valid.

    Examples of authentication rules:

    • {realm: 'Authentication required', username: 'capo', password: 'dei capi'}

    • {realm: 'Authentication required', check: function(user, pass, callback) {return callback(user+' '+pass == 'capo dei capi');}}

    Some code examples

        spritz = require('spritz');
    // Start (with so many processes as CPU cores)
        port: 8090,
        processes: require('os').cpus().length
    // Listen on a static route
    spritz.on('/', function(req, res){
        // Answer
        spritz.text(req, res, 'Aperol o Campari?', 200);
    // Answer with a JSON
    spritz.on('/json', function(req, res){
        spritz.json(req, res, {some: "json", other: 1});
    // Listen on a RegExp based url pattern.
    spritz.on(/^\/(x.*)/, function(req, res){
        // console.log("User asked for ", RegExp.$1);
        // Answer with a text. Status code and headers are optional
        spritz.text(req, res, 'Soda?', 200, {'content-type':'text/plain'});
    // Listen on a static route only for POST
    spritz.on('/post', {method:"POST"}, function(req, res){
        // Send a JSON with the POST arguments and files
        spritz.json(req, res, {args: req.POSTargs, files: req.POSTfiles});
    // Listen on a static route. Tell to not read the POST data, so it will be proxied.
    spritz.on('/npm/', {dontReadPOSTData:true}, function(req, res){
        // Proxy the request (both syntaxes are supported)
        spritz.proxy(req, res, "");
    //  spritz.proxy(req, res, "", 9999, {proto: "http", timeout: 2000});
    // Status handler
    spritz.on(404, function(req, res){
        spritz.text(req, res, '404 - Cosa vuole, signore?', 404);
    spritz.on(200, function(req, res){
    // Set a hook
    spritz.on('#arrive', function(req, res, args, callback){
        console.log('Got a request to '+req.url);
        return callback();
    // Use a (template) module
    spritz.on('/use-a-template/', function(req, res){
        spritz.template(req, res, 'template.jst', {some: 'value', other: 'value'});
    // Set an authentication rule for a specific URL pattern (pattern is optional)
    //spritz.auth(/^\/pass/, {check: function(u, p, cb){ return cb(null, u=="capo" && p=="dei capi"); }});
    spritz.on(/passwd/, { auth: {username: "capo", password: "dei capi"}}, function(req, res){
        // Answer with a file. Status code and headers are optional
        // console.log("Serving /etc/passwd to "+req.authUser);
        spritz.staticfile(req, res, "/etc/passwd", 200, {'content-type': 'text/plain'});


    npm i spritz

    DownloadsWeekly Downloads






    Unpacked Size

    49.1 kB

    Total Files


    Last publish


    • doliveira