superstatic

library10.0.0jsnpmunverified

Superstatic is an enhanced static web server designed for modern web applications, currently at version 10.0.0. Originally built to power Firebase Hosting, it provides robust features such as HTML5 pushState support, clean URLs (removing `.html` extensions), advanced caching, and configurable routing via rewrites and redirects. It offers a flexible configuration system through `superstatic.json` or `firebase.json` files. The project maintains an active release cadence, frequently updating dependencies and Node.js engine support, with recent versions focusing on compatibility with newer Node.js LTS releases. Key differentiators include its rich configuration options for dynamic static site behavior, strong support for Single Page Applications (SPAs), and its historical role in Firebase's infrastructure.

web-framework aws

npm install superstatic

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SUPERSTATIC

superstatic

web-frameworkjavascriptv10.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server

✓ import { Server } from 'superstatic';

✗ const Server = require('superstatic');

The primary programmatic API is the `Server` class, typically imported as a named export. TypeScript types are provided.

superstatic cli (global)

✓ npm install -g superstatic

✗ import superstatic from 'superstatic';

For CLI usage, `superstatic` is commonly installed globally and run directly from the command line, rather than imported programmatically via a default export.

Server (CommonJS)

✓ const { Server } = require('superstatic');

✗ const Server = require('superstatic').default;

For CommonJS environments, the `Server` class is available as a named property of the `require`'d module.

Initializes and starts a Superstatic server instance programmatically, demonstrating basic configuration for serving a 'public' directory, enabling clean URLs, setting up SPA rewrites, and adding custom cache headers.

import { Server } from 'superstatic'; import * as path from 'path'; async function startStaticServer() { const server = new Server({ port: 8080, host: '127.0.0.1', cwd: process.cwd(), // Serve from current directory by default config: { public: 'public', // Serve 'public' directory relative to CWD cleanUrls: true, rewrites: [{ source: '**', destination: '/index.html' }], // SPA rewrite headers: [ { source: '**/*.@(jpg|jpeg|gif|png|svg)', headers: [{ key: 'Cache-Control', value: 'max-age=3600' }] } ] } }); const app = server.listen(() => { console.log(`Superstatic server running on http://127.0.0.1:8080`); }); // Optional: Handle process exit for graceful shutdown process.on('SIGINT', () => { console.log('Shutting down server...'); app.close(() => { console.log('Server gracefully shut down.'); process.exit(0); }); }); } startStaticServer().catch(console.error);

superstatic --version

Debug

Known issues

breakingThe `cleanUrls` configuration option no longer accepts an array of globs; it must be a boolean value (`true` or `false`).

fix

Update your `superstatic.json` or `firebase.json` configuration to set `cleanUrls` to `true` or `false`.

affects: >=6.0.0

breakingNode.js 10 support has been dropped. Running Superstatic on Node.js 10 will likely result in errors or unexpected behavior.

fix

Upgrade your Node.js runtime to version 12 or newer. Refer to the `engines.node` field in `package.json` for supported versions.

affects: >=8.0.0

breakingNode.js 18 support has been removed. Superstatic now requires Node.js 20, 22, or 24.

fix

Upgrade your Node.js runtime to version 20, 22, or 24. Always check the `engines.node` field for the latest supported versions.

affects: >=10.0.0

gotchaUnicode paths in redirects may not have been handled correctly in earlier versions.

fix

Upgrade to Superstatic v9.1.0 or newer to ensure correct handling of unicode characters in redirect paths.

affects: <9.1.0

gotchaThe internal URL parsing mechanism switched from `fast-url-parser` to Node.js's built-in URL parser. This change could introduce subtle behavioral differences for highly specific or edge-case URL structures.

fix

Test your application's routing thoroughly after upgrading to v9.2.0 or higher if you rely on very specific URL parsing behaviors, especially for complex query strings or unusual path segments.

affects: >=9.2.0

gotchaIn Node.js 22, the `mtime` property from `fs.stat` was sometimes unavailable. This was fixed in `superstatic` v9.1.0.

fix

If running on Node.js 22, ensure you are using `superstatic` v9.1.0 or newer to avoid potential issues with file modification times.

affects: >=9.9.0 <=9.1.0 (on Node.js 22)

Errors

Common errors & fixes

Error: Cannot GET / (or other path) / 404 Not Found

The requested file or path does not exist in the configured `public` directory, or the `public` directory is misconfigured.

fix

Verify that your `public` configuration setting in `superstatic.json` or `firebase.json` correctly points to the directory containing your static assets, relative to the configuration file, and that the requested file exists.

TypeError: config.cleanUrls.includes is not a function

Attempting to use an array for the `cleanUrls` configuration option, which is no longer supported.

fix

Set `cleanUrls` to a boolean value (`true` or `false`) in your `superstatic.json` or `firebase.json` file. Array support for `cleanUrls` was removed in v6.0.0.

Node.js version not supported. Superstatic requires Node.js 20 || 22 || 24.

You are running an unsupported version of Node.js.

fix

Upgrade your Node.js runtime environment to one of the officially supported LTS versions (20, 22, or 24). You can use a tool like `nvm` to manage Node.js versions.

Error: Cannot redirect to an empty string

A `redirects` rule is configured with an empty or invalid `destination` property, or a source pattern results in an empty segment for the destination.

fix

Review your `redirects` configuration in `superstatic.json` or `firebase.json` and ensure all `destination` paths are valid and non-empty. Pay special attention to segmented redirects (`:segment`) to ensure they resolve correctly.

Upgrade

Version history

10.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/firebase/superstatic ↗

packagehttps://www.npmjs.com/package/superstatic ↗

homepagehttps://superstatic.org ↗