{"id":15390,"library":"superstatic","title":"Superstatic Static File Server","description":"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.","status":"active","version":"10.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/firebase/superstatic","tags":["javascript","static","server","firebase","hosting","pushstate","html5","router","file","typescript"],"install":[{"cmd":"npm install superstatic","lang":"bash","label":"npm"},{"cmd":"yarn add superstatic","lang":"bash","label":"yarn"},{"cmd":"pnpm add superstatic","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary programmatic API is the `Server` class, typically imported as a named export. TypeScript types are provided.","wrong":"const Server = require('superstatic');","symbol":"Server","correct":"import { Server } from 'superstatic';"},{"note":"For CLI usage, `superstatic` is commonly installed globally and run directly from the command line, rather than imported programmatically via a default export.","wrong":"import superstatic from 'superstatic';","symbol":"superstatic cli (global)","correct":"npm install -g superstatic"},{"note":"For CommonJS environments, the `Server` class is available as a named property of the `require`'d module.","wrong":"const Server = require('superstatic').default;","symbol":"Server (CommonJS)","correct":"const { Server } = require('superstatic');"}],"quickstart":{"code":"import { Server } from 'superstatic';\nimport * as path from 'path';\n\nasync function startStaticServer() {\n  const server = new Server({\n    port: 8080,\n    host: '127.0.0.1',\n    cwd: process.cwd(), // Serve from current directory by default\n    config: {\n      public: 'public', // Serve 'public' directory relative to CWD\n      cleanUrls: true,\n      rewrites: [{ source: '**', destination: '/index.html' }], // SPA rewrite\n      headers: [\n        {\n          source: '**/*.@(jpg|jpeg|gif|png|svg)',\n          headers: [{ key: 'Cache-Control', value: 'max-age=3600' }]\n        }\n      ]\n    }\n  });\n\n  const app = server.listen(() => {\n    console.log(`Superstatic server running on http://127.0.0.1:8080`);\n  });\n\n  // Optional: Handle process exit for graceful shutdown\n  process.on('SIGINT', () => {\n    console.log('Shutting down server...');\n    app.close(() => {\n      console.log('Server gracefully shut down.');\n      process.exit(0);\n    });\n  });\n}\n\nstartStaticServer().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"fix":"Update your `superstatic.json` or `firebase.json` configuration to set `cleanUrls` to `true` or `false`.","message":"The `cleanUrls` configuration option no longer accepts an array of globs; it must be a boolean value (`true` or `false`).","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Upgrade your Node.js runtime to version 12 or newer. Refer to the `engines.node` field in `package.json` for supported versions.","message":"Node.js 10 support has been dropped. Running Superstatic on Node.js 10 will likely result in errors or unexpected behavior.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Upgrade your Node.js runtime to version 20, 22, or 24. Always check the `engines.node` field for the latest supported versions.","message":"Node.js 18 support has been removed. Superstatic now requires Node.js 20, 22, or 24.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Upgrade to Superstatic v9.1.0 or newer to ensure correct handling of unicode characters in redirect paths.","message":"Unicode paths in redirects may not have been handled correctly in earlier versions.","severity":"gotcha","affected_versions":"<9.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=9.2.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.","message":"In Node.js 22, the `mtime` property from `fs.stat` was sometimes unavailable. This was fixed in `superstatic` v9.1.0.","severity":"gotcha","affected_versions":">=9.9.0 <=9.1.0 (on Node.js 22)"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The requested file or path does not exist in the configured `public` directory, or the `public` directory is misconfigured.","error":"Error: Cannot GET / (or other path) / 404 Not Found"},{"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.","cause":"Attempting to use an array for the `cleanUrls` configuration option, which is no longer supported.","error":"TypeError: config.cleanUrls.includes is not a function"},{"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.","cause":"You are running an unsupported version of Node.js.","error":"Node.js version not supported. Superstatic requires Node.js 20 || 22 || 24."},{"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.","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.","error":"Error: Cannot redirect to an empty string"}],"ecosystem":"npm"}