superstatic

What is superstatic?

Superstatic is a static file server that supports modern web development features such as clean URLs, custom headers, and redirects. It is often used for serving static websites and single-page applications (SPAs) with ease.

What are superstatic's main functionalities?

Serving Static Files

This feature allows you to serve static files from a specified directory. In this example, the server serves files from the './public' directory on port 3474.

const superstatic = require('superstatic');
const connect = require('connect');

const app = connect().use(superstatic({
  root: './public'
}));

app.listen(3474, () => {
  console.log('Server running on port 3474');
});

Clean URLs

This feature enables clean URLs, which means you can serve files without the '.html' extension. For example, 'example.com/about' will serve 'about.html'.

const superstatic = require('superstatic');
const connect = require('connect');

const app = connect().use(superstatic({
  root: './public',
  cleanUrls: true
}));

app.listen(3474, () => {
  console.log('Server running on port 3474');
});

Custom Headers

This feature allows you to set custom headers for your files. In this example, all HTML files will have a 'Cache-Control' header set to 'no-cache'.

const superstatic = require('superstatic');
const connect = require('connect');

const app = connect().use(superstatic({
  root: './public',
  headers: [{
    source: '**/*.html',
    headers: [{
      key: 'Cache-Control',
      value: 'no-cache'
    }]
  }]
}));

app.listen(3474, () => {
  console.log('Server running on port 3474');
});

Redirects

This feature allows you to set up redirects. In this example, requests to '/old-page' will be redirected to '/new-page' with a 301 status code.

const superstatic = require('superstatic');
const connect = require('connect');

const app = connect().use(superstatic({
  root: './public',
  redirects: [{
    source: '/old-page',
    destination: '/new-page',
    type: 301
  }]
}));

app.listen(3474, () => {
  console.log('Server running on port 3474');
});

Other packages similar to superstatic

http-server

http-server is a simple, zero-configuration command-line static HTTP server. It is easy to use and can serve static files quickly, but it lacks some of the advanced features like custom headers and redirects that superstatic offers.

live-server

live-server is a simple development HTTP server with live reload capability. It is great for development purposes as it automatically reloads the page when files change. However, it does not offer features like clean URLs or custom headers.

serve

serve is a static file serving and directory listing tool. It is highly configurable and supports features like clean URLs and custom headers, similar to superstatic. However, it is more focused on simplicity and ease of use.

README

Superstatic

Superstatic is an enhanced static web server that was built to power Divshot. It has fantastic support for HTML5 pushState applications, clean URLs, caching, and MANY other goodies.

Documentation

• Installation
• Usage
• Configuration
• API
  • Middleware
  • Server
• Run Tests
• Changelog
• Contributing

Installation

Superstatic should be installed globally using npm:

For use via CLI

$ npm install -g superstatic

For use via API

npm install superstatic --save

Usage

By default, Superstatic will simply serve the current directory on port 3474. This works just like any other static server:

$ superstatic

or aliased as

$ ss

You can optionally specify the directory, port and hostname of the server:

$ superstatic public --port 8080 --host 127.0.0.1

Where it gets interesting is with Superstatic's JSON configuration file.

Configuration

Superstatic reads special configuration from a JSON file (either superstatic.json or divshot.json by default, configurable with -c). This JSON file enables enhanced static server functionality beyond simply serving files.

root: by default, Superstatic will serve the current working directory (or the ancestor of the current directory that contains the configuration json being used). This configuration key specifies a directory relative to the configuration file that should be served. For example, if serving a Jekyll app, this might be set to "_site". A directory passed as an argument into the command line app supercedes this configuration directive.

clean_urls: if true, all .html files will automatically have their extensions dropped. If .html is used at the end of a filename, it will perform a 301 redirect to the same path with .html dropped.

All paths have clean urls

{
  "clean_urls": true
}

Only specific paths get clean urls

{
  "clean_urls": ["/app/**", "/!components/**"]
}

routes: you can specify custom route recognition for your application by supplying an object to the routes key. Use a single star * to replace one URL segment or a double star to replace an arbitrary piece of URLs. This works great for single page apps. An example:

{
  "routes": {
    "app/**":"application.html",
    "projects/*/edit":"projects.html"
  }
}

Note: There is no guarantee of the order that your routes will be parsed when using only an object. If you need to ensure that your routes are parsed in order, please wrap them in an array. An example:

{
  "routes": [
    {
     "app/**": "application.html",
     "profile/**": "profile.html"
    },
    {"**": "index.html"}
  ]
}

redirects: you can specify to have certain url paths be redirected (specifying a custom HTTP status code, or which defaults to 301) to other url paths by supplying an object to the redirects key. Route path matching is similar to using custom routes. For example:

Default 301 redirect

{
  "redirects": {
    "/some/old/path": "/some/new/path"
  }
}

Custom HTTP status code

{
  "redirects": {
    "/some/old/path": {
      "status": 302,
      "url": "/some/new/path"
    }
  }
}

Route segments are also supported in the redirects configuration. Segmented redirects also support custom status codes (see above):

{
  "redirects": {
    "/old/:segment/path": "/new/path/:segment"
  }
}

In this example, /old/custom-segment/path redirect to /new/path/custom-segment

error_page: the path to the page that you want to render 404 errors if an unrecognized URL is supplied. For example, error.html.

cache_control: by default, all pages served by superstatic have cache control headers set at 1 hour. To change them, you can supply an object containing file globs and ages (in seconds). You can also specify false to indicate that no caching should be performed, and a string to manually set the cache control header. An example:

{
  "cache_control": {
    "nocache/**": false,
    "**/*.html": 600,
    "private/**": "private, max-age=1200"
  }
}

Note that you can pass the --no-cache option when you run the server to serve all content without caching. This is good to use during development when you want fresh content served on each request.

Headers: Superstatic allows you to set the response headers for the given routing configuration.

{
  "headers": {
    "/cors-stuff/**": {
      "Access-Control-Allow-Origin": "*"
    },
    "/scripts/**": {
      "content-type": "text/javascript"
    }
  }
}

trailing_slash: Have full control over whether or not your app has or doesn't have trailing slashes. By default, Superstatic will make assumptions for on the best times to add or remove the trailing slash. Other options include true, which always adds a trailing slash, and false, which always removes the trailing slash.

{
  "trailing_slash": true
}

API

Superstatic is available as a middleware and a standalone Connect server. This means you can plug this into your current server or run your own static server using Superstatic's server.

Middleware

var superstatic = require('superstatic')
var connect = require('connect');

var app = connect()
	.use(superstatic(/* options */));

app.listen(3000, function () {

});

superstatic([options])

Insantiates middleware. See an example for detail on real world use.

• options - Optional configuration:
  • config - A file path to your application's configuration file (see Configuration) or an object containing your application's configuration.
  • protect - Adds HTTP basic auth. Example: username:password
  • env- A file path your application's environment variables file or an object containing values that are available at the urls /__/env.json and /__/env.js. See the documentation detail on environment variables.
  • cwd - The current working directory to set as the root. Your application's root configuration option will be used relative to this.
  • services - An object containing various Superstatic services.

Server

var superstatic = require('superstatic').server;

var app = superstatic(/* options */);

var server = app.listen(function () {

});

Since Superstatic's server is a barebones Connect server using the Superstatic middleware, see the Connect documentation on how to correctly instantiate, start, and stop the server.

superstatic([options])

Instantiates a Connect server, setting up Superstatic middleware, port, host, debugging, compression, etc.

• options - Optional configuration. Uses the same options as the middleware, plus a few more options:
  • port - The port of the server. Defaults to 3474.
  • host or hostname - The hostname of the server. Defaults to localhost.
  • errorPage - A file path to a custom error page. Defaults to Superstatic's error page.
  • debug - A boolean value that tells Superstatic to show or hide network logging in the console. Defaults to false.
  • gzip - A boolean value that tells Superstatic to gzip response body. Defaults to false.

Run Tests

In superstatic module directory:

npm install
npm test

Contributing

We LOVE open source and open source contributors. If you would like to contribute to Superstatic, please review our contributing guidelines before your jump in and get your hands dirty.