spa-server v1.0.0

Node SPA Server

Extensible Node Web Server based on top of Connect and serve-static to help you run your SPA's (Single Page Applications).

Just point it to your web root directory and it will serve all your static goodness right away! However, when missing URL is requested it performs smart fallback lookup (fully configurable).

Also you can use your own custom middleware with it (or a third-party).

Can be used with Gulp.

Usage

var serverFactory = require('spa-server');

var server = serverFactory.create({
  path: './build',
  port: 80,
  fallback: fallbackConfig
});

server.start();

Please see configuration section for different fallback configurations.

With Gulp

This module can be invoked inside of a Gulp task for convenience.

var serverFactory = require('spa-server');

gulp.task('webserver', function () {
  var server = serverFactory.create({
    path: './build',
    port: 80,
    fallback: fallbackConfig
  });

  server.start();
});

Just add code above to your gulpfile.js and run gulp webserver after that.

Please see configuration section for different fallback configurations.

Installation

It's exactly like you've already guessed:

npm install --save spa-server or npm install --save-dev spa-server.

Configuration

Fallback Lookup

You can configure fallback lookup using fallback configuration property. By default, lookup functionality is disabled.

Single URL

If you will set fallback option to a string value, e.g.: /index.html, it will serve the specified URL for all missing (404) requests. You can point server to your root application file that way.

var serverFactory = require('spa-server');

var server = serverFactory.create({
  path: './build',
  port: 80,
  fallback: '/application.html'
});

server.start();

Smart lookup

However, it's OK to use single URL fallback, but it could be unfair to some static resources, cause it will serve text/html even if missing.js file was requested.

To counter this, the smart fallback lookup was introduced. With it, you can specify fallback URL for each individual mime type. The server will do it's best to determine request's mime type by examining it's headers and file extension (if present in URL).

var serverFactory = require('spa-server');

var server = serverFactory.create({
  path: './build',
  port: 80,
  fallback: {
    'text/html' : '/application.html',
    'image/*'   : '/images/default.png',
    '*'         : '/404.html'
  }
});

server.start();

This configuration will serve application.html file for every missing HTML request and will serve default.png for every missing image. The 404.html will be served for all other missing requests, e.g. missing.js.

Possible mime type specifiers are:

• '{type}/{subtype}' — matches specific type and subtype
• '{type}/*' — matches all subtypes of specified type
• '*' — matches everything

Fallback filter will process the specified rules trying to match most explicit ones first and least explicit later. The order doesn't matters, but is recommended for readability.

We are using node mime module internally to map filename extensions to mime types. You can also use it to specify explicit mime types, for better stability.

var serverFactory = require('spa-server');
var mime = require('mime');

var server = serverFactory.create({
  path: './build',
  port: 80,
  fallback: {
    mime.lookup('html') : '/application.html',
    mime.lookup('js') : '/js/default.js'
  }
});

server.start();

Handler function

And for ultimate control of the fallback filter you can pass a function of your own! It will receive the standard request and response objects and will need to return fallback URL. You can also return null to fallback to default 404 page.

var serverFactory = require('spa-server');

var matcher = new RegExp('\\.html?$');

var server = serverFactory.create({
  path: './build',
  port: 80,
  fallback: function (request, response) {
    // For all missing HTML files.
    if (matcher.test(request.url)) {
      // Falling back to main application file.
      return '/application.html';
    }
    // Falling back to default server 404 page.
    return null;
  }
});

server.start();

Custom middleware

You can pass list of your own middleware via middleware configuration option, all passed middleware will be added to underlying Connect's instance. With this option you can take full control of the webserver.

Each element of the middleware option should be either a function or an object.

Middleware as a function

All function elements from the middleware list will be added before the serve-static and built-in fallback handlers to the stack of Connect's middleware.

var serverFactory = require('spa-server');
var favicon = require('serve-favicon');

var server = serverFactory.create({
  path: './build',
  port: 80,
  middleware: [
    // Do-nothing middleware.
    function (request, response, next) {
      next();
    },
    // Adding custom header.
    function (request, response, next) {
      response.addHeader('X-My-Custom-Header', 'Content');
      next();
    },
    // Using third-party middleware.
    favicon(__dirname + '/public/favicon.ico')
  ]
});

server.start();

Middleware as an object

Sometimes it's not enough to add middleware just before the built-in handlers. The are situations where you want to add custom middleware before the fallback handler, but after the serve-static middleware. We are providing a very powerful mechanism to achieve this.

You can add an object to the middleware list to not only provide the custom function, but to specify where this function should be placed in the Connect's middleware stack.

The following keys are supported in the object:

• middleware — your custom middleware function
• before / after — name of the built-in middleware that your function will be added before or after (use only one of them at the same time)

The following position specifier's values are possible:

• $start — meta-value to define start of the stack
• serve-static — middleware to serve static content (will not call next middleware if content is found)
• fallback — middleware with fallback functionality
• $end — meta-value to define end of the stack

var serverFactory = require('spa-server');
var favicon = require('serve-favicon');

var server = serverFactory.create({
  path: './build',
  port: 80,
  middleware: [
  
    // Will be added to the top of the stack.
    {
      middleware: firstMiddleware,
      before: '$start'
    },

    // Without position specifier,
    // will be added to the top of the stack.
    {
      middleware: myMiddleware
    },
    
    // The same as two above, but even shorter.
    myMiddleware,
    
    // Will be added after serve-static.
    {
      middleware: afterServeStaticMiddleware,
      after: 'serve-static'
    },
    
    // Will be added before fallback handler.
    {
      middleware: beforeFallbackHandler,
      before: 'fallback'
    },
    
    // Will be added to the end of the stack.
    {
      middleware: finalMiddleware,
      after: '$end'
    },

  ]
});

server.start();

Notice: if you place your middleware after the $end it still will not guarantee that it will be executed. Position specifier only affect the placement of your middleware in the Connect's stack.

Changelog

Please see the complete changelog for list of changes.

Contributors

This library was made possible by it's contributors.

Feedback

If you have found a bug or have another issue with the library — please create an issue.

If you have a question regarding the library or it's integration with your project — consider asking a question at StackOverflow and sending me a link via E-Mail. I will be glad to help.

Have any ideas or propositions? Feel free to contact me by E-Mail.

Cheers!

License

The MIT License (MIT)

Copyright (c) 2015—2016 Slava Fomin II, BETTER SOLUTIONS

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.