• Stars
    star
    1,097
  • Rank 42,257 (Top 0.9 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created about 11 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Superstatic: a static file server for fancy apps.

Superstatic NPM Module NPM download count Build Status Code Climate

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

Documentation

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

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

$ superstatic public --port 8080 --host 127.0.0.1

Configuration

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

public: 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.

cleanUrls: 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

{
  "cleanUrls": true
}

rewrites: 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:

{
  "rewrites": [
    {"source":"app/**","destination":"/application.html"},
    {"source":"projects/*/edit","destination":"/projects.html"}
  ]
}

redirects: you can specify certain url paths to be redirected to another url by supplying configuration to the redirects key. Path matching is similar to using custom routes. redirects use the 301 HTTP status code by default, but this can be overridden by configuration.

{
  "redirects": [
    {"source":"/some/old/path", "destination":"/some/new/path"},
    {"source":"/firebase/*", "destination":"https://www.firebase.com", "type": 302}
  ]
}

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

{
  "redirects": [
    {"source":"/old/:segment/path", "destination":"/new/path/:segment"}
  ]
}

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

headers: Superstatic allows you to set the response headers for certain paths as well:

{
  "headers": [
    {
      "source" : "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
      "headers" : [{
        "key" : "Access-Control-Allow-Origin",
        "value" : "*"
      }]
    }, {
      "source" : "**/*.@(jpg|jpeg|gif|png)",
      "headers" : [{
        "key" : "Cache-Control",
        "value" : "max-age=7200"
      }]
    }, {
      "source" : "404.html",
      "headers" : [{
        "key" : "Cache-Control",
        "value" : "max-age=300"
      }]
    }]
  }
}

trailingSlash: 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.

{
  "trailingSlash": true
}

i18n: Internationalized content can be served based on accept-language or x-country-code headers.

Imagine a setup with the following files:

- public/
  - index.html
  - i18n/
    - fr_ca/
      - index.html
    - ALL_ca/
      - index.html
    - fr/
      - index.html

With i18n enabled, when a request is received for /index.html with the accept-language header set to fr (and no x-country-code), the content at public/i18n/fr/index.html will be returned as a response.

If accept-language: fr and x-country-code: ca are passed, the content at public/i18n/fr_ca/index.html will be returned for /index.html.

For more information about how content is resolved when using i18n, see the Firebase Hosting documentation of the feature.

{
  "i18n": {
    "root": "/intl"
  }
}

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])

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

  • options - Optional configuration:
    • fallthrough - When false, render a 404 page from within Superstatic rather than calling through to the next middleware. Defaults to true.
    • config - A file path to your application's configuration file (see Configuration) or an object containing your application's configuration. If an object is provided, it will be merged into existing config in a superstatic.json.
    • 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 made 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 public configuration option will be used relative to this.
    • compression - An option which controls superstatic's response compression. Pass in a standard compression(req, res, next) Express middleware function to override the default compression behavior (for example, require shrink-ray to enable advanced compression schemes such as brotli, or require node.js' stock compression middleware yourself to change the compression quality and caching behavior). Any other truthy value will default to the stock node.js middleware.

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.
    • compression - A boolean value that tells Superstatic to serve gzip/deflate compressed responses based on the request Accept-Encoding header and the response Content-Type header. Defaults to false.
    • gzip [DEPRECATED] - A boolean value which is now equivalent in behavior to compression. Defaults to false.

Providers

Superstatic reads content from providers. The default provider for Superstatic reads from the local filesystem. Other providers can be substituted when initializing Superstatic:

superstatic({
  provider: require('superstatic-someprovider')({
    provider: 'options'
  })
});

Authoring Providers

Implementing a new provider is quite simple. You simply need to create a function that takes a request and pathname and returns a Promise. The Promise should:

  1. Resolve null when content isn't found (i.e. a 404 response).
  2. Resolve with a metadata object as described below when content is found.
  3. Reject when an error occurs in the content-fetching process.

The metadata object returned by a provider needs the following properties:

  • stream: A readable stream for the content.
  • size: The length of the content.
  • etag: (optional) a content-unique string such as an MD5 hash computed from the content
  • modified: (optional) a Date object for when the content was last modified

A simple in-memory store provider can be found at lib/providers/memory.js in this repo as a simple reference example of a provider.

Note: The pathname will be URL-encoded. You should make sure your provider properly handles files with non-standard characters (spaces, unicode, etc).

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 you jump in and get your hands dirty.

More Repositories

1

functions-samples

Collection of sample apps showcasing popular use cases using Cloud Functions for Firebase
JavaScript
12,063
star
2

flutterfire

🔥 A collection of Firebase plugins for Flutter apps.
Dart
8,671
star
3

quickstart-android

Firebase Quickstart Samples for Android
Java
8,563
star
4

firebase-js-sdk

Firebase Javascript SDK
TypeScript
4,830
star
5

quickstart-js

Firebase Quickstart Samples for Web
HTML
4,818
star
6

FirebaseUI-Android

Optimized UI components for Firebase
Java
4,628
star
7

firebaseui-web

FirebaseUI is an open-source JavaScript library for Web that provides simple, customizable UI bindings on top of Firebase SDKs to eliminate boilerplate code and promote best practices.
JavaScript
4,558
star
8

firebase-tools

The Firebase Command Line Tools
TypeScript
3,994
star
9

firebase-ios-sdk

Firebase iOS SDK
Objective-C
3,583
star
10

quickstart-ios

Firebase Quickstart Samples for iOS
Swift
2,773
star
11

firebase-android-sdk

Firebase Android SDK
Java
2,244
star
12

codelab-friendlychat-web

The source for the Firebase codelab for building a cross-platform chat app
JavaScript
1,749
star
13

firebase-admin-node

Firebase Admin Node.js SDK
TypeScript
1,621
star
14

FirebaseUI-iOS

iOS UI bindings for Firebase.
Objective-C
1,507
star
15

geofire-js

GeoFire for JavaScript - Realtime location queries with Firebase
TypeScript
1,443
star
16

firebaseui-web-react

React Wrapper for firebaseUI Web
JavaScript
1,262
star
17

firebase-admin-go

Firebase Admin Go SDK
Go
1,142
star
18

firebase-functions

Firebase SDK for Cloud Functions
TypeScript
1,024
star
19

firebase-admin-python

Firebase Admin Python SDK
Python
1,019
star
20

quickstart-nodejs

JavaScript
895
star
21

extensions

Source code for official Firebase extensions
TypeScript
892
star
22

quickstart-unity

Firebase Quickstart Samples for Unity
C#
775
star
23

snippets-android

Android snippets for firebase.google.com
Java
762
star
24

snippets-web

Web snippets for firebase.google.com
JavaScript
749
star
25

genkit

An open source framework for building AI-powered apps with familiar code-centric patterns. Genkit makes it easy to develop, integrate, and test AI features with observability and evaluations. Genkit works with various models and platforms.
TypeScript
701
star
26

geofire-java

GeoFire for Java - Realtime location queries with Firebase
Java
671
star
27

firebase-admin-java

Firebase Admin Java SDK
Java
527
star
28

friendlyeats-web

JavaScript
467
star
29

geofire-objc

GeoFire for Objective-C - Realtime location queries with Firebase
Objective-C
440
star
30

snippets-node

Node.js snippets for firebase.google.com
JavaScript
369
star
31

firebase-admin-dotnet

Firebase Admin .NET SDK
C#
367
star
32

quickstart-testing

Samples demonstrating how to test your Firebase app
TypeScript
335
star
33

firebase-tools-ui

A local-first UI for Firebase Emulator Suite.
TypeScript
269
star
34

friendlyeats-android

Cloud Firestore Android codelab
Kotlin
261
star
35

codelab-friendlychat-android

Firebase FriendlyChat codelab
Kotlin
243
star
36

firebase-cpp-sdk

Firebase C++ SDK
C++
230
star
37

quickstart-java

Quickstart samples for Firebase Java Admin SDK
Java
224
star
38

firebase-functions-test

TypeScript
211
star
39

quickstart-cpp

Firebase Quickstart Samples for C++
C++
190
star
40

fastlane-plugin-firebase_app_distribution

fastlane plugin for Firebase App Distribution. https://firebase.google.com/docs/app-distribution
Ruby
166
star
41

friendlypix-ios

Friendly Pix iOS is a sample app demonstrating how to build an iOS app with the Firebase Platform.
Swift
166
star
42

quickstart-flutter

Dart
138
star
43

firebase-functions-python

Python
136
star
44

geofire-android

GeoFire for Android apps
Java
133
star
45

firebase-unity-sdk

The Firebase SDK for Unity
C#
128
star
46

friendlyeats-ios

Swift
127
star
47

snippets-ios

iOS snippets used in firebase.google.com
Objective-C
121
star
48

firebaseopensource.com

Source for firebase open source site
TypeScript
118
star
49

quickstart-python

Jupyter Notebook
115
star
50

FirebaseUI-Flutter

Dart
102
star
51

codelab-friendlychat-ios

Swift
68
star
52

snippets-rules

Snippets for security rules on firebase.google.com
TypeScript
45
star
53

emulators-codelab

JavaScript
44
star
54

oss-bot

Robot friend for open source repositories
TypeScript
36
star
55

firebase-bower

Firebase Web Client
JavaScript
35
star
56

snippets-flutter

Dart
30
star
57

snippets-go

Golang snippets for firebase docs
Go
24
star
58

snippets-java

Java snippets for firebase.google.com
Java
17
star
59

firebase-docs

TypeScript
16
star
60

abseil-cpp-SwiftPM

C++
13
star
61

firebase-testlab-instr-lib

Java
13
star
62

snippets-cpp

C++ snippets for firebase.google.com
C++
12
star
63

SpecsStaging

SpecsStaging
11
star
64

SpecsTesting

Ruby
11
star
65

rtdb-to-csv

JavaScript
11
star
66

appquality-codelab-ios

Firebase iOS App Quality Codelab
Objective-C
11
star
67

level-up-with-firebase

C#
9
star
68

boringSSL-SwiftPM

C++
8
star
69

firestore-bundle-builder

TypeScript
7
star
70

.github

Default configuration for Firebase repos
6
star
71

nginx

This repo is a PUBLIC FORK
C
6
star
72

SpecsDev

6
star
73

snippets-python

Python snippets for firebase.google.com
4
star
74

firebase-release-dashboard

JavaScript
4
star
75

ok

HTTPS CDN Proxy Healthy Check
4
star
76

grpc-SwiftPM

C++
3
star
77

crashlytics-testapps

Java
2
star
78

data-connect-ios-sdk

Swift
2
star
79

.allstar

1
star