Superstatic Static File Server

Common errors

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

  cause 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

  cause 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.

  cause 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

  cause 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.

Warnings

• breaking The `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`.
• breaking Node.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.
• breaking Node.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.
• gotcha Unicode 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.
• gotcha The 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.
• gotcha In 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.

Install

• npm install superstatic npm
• yarn add superstatic yarn
• pnpm add superstatic pnpm

Imports

• Server
  wrong:

  const Server = require('superstatic');

  correct:

  import { Server } from 'superstatic';

  The primary programmatic API is the `Server` class, typically imported as a named export. TypeScript types are provided.
• superstatic cli (global)
  wrong:

  import superstatic from 'superstatic';

  correct:

  npm install -g 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)
  wrong:

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

  correct:

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

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

Quickstart

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