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.
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.
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.
It's exactly like you've already guessed:
npm install --save spa-server or npm install --save-dev spa-server.
| Option | Type | Default | Description |
|---|---|---|---|
| path | string |
'.' |
Path to your web root |
| hostname | string |
undefined |
Hostname to listen for, any when not set |
| port | integer |
8888 |
Listening port |
| fallback | string or object or function |
undefined |
Fallback lookup configuration, see below |
| serveStaticConfig | object |
See the code | Configuration object for serve-static middleware, see it's options |
| middleware | array |
[] |
List of your custom middleware |
You can configure fallback lookup using fallback configuration property.
By default, lookup functionality is disabled.
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();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();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();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.
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();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 functionbefore/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 stackserve-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.
Install globally via npm:
npm install spa-server -g
This will install spa-server globally so that it can be run from the command line.
spa-server [options] [path]
-a Listen address. Defaults to 0.0.0.0
-d Show dotfiles. Defaults to ignore
-f Fallback URL. Example:
spa-server -f "/index.html" .
-F Fallback handler function or object. Example:
spa-server -F "({'*': '/index.html'})" .
-h or -? Show help
-l Log format. Defaults to combined. See available formats
-m Middleware
-p Listen port. Defaults to 8888.
-q Quiet mode. Disables logging.
-s Servestatic config object. See Servestatic options
# Set cache-control max-age
spa-server -s "({maxAge: 10000})" .
# Set CORS header
spa-server -s "({setHeaders: ((res, path) => {res.setHeader('Access-Control-Allow-Origin', '*')})})" .
Please see the complete changelog for list of changes.
This library was made possible by it's contributors.
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!
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.