Node.js Static File Server

2.2.1 · abandoned · verified Sun Apr 19

The `static-server` package provides a minimalistic HTTP server explicitly designed to serve static files from a local directory. It is primarily intended for local development, rapid prototyping, or testing scenarios, with its maintainers stating it is "obviously not" suitable for production environments and "preferably not" for high-traffic applications. The current stable version, 2.2.1, was released several years ago, and the project appears to be abandoned, with no significant updates in a long time. It differentiates itself by its extreme simplicity and minimal configuration options, serving only static resources without support for server-side scripting languages like PHP, Ruby, or Python. It's a foundational utility rather than a feature-rich web server.

Common errors

```
Error: listen EADDRINUSE :::<port_number>
```
cause The specified port (e.g., 1337) is already in use by another application or process on your system.

fix Choose a different port for the server by modifying the `port` option (e.g., `port: 8080`), or identify and terminate the process currently using the conflicting port.
```
404 Not Found (in browser/console)
```
cause The requested file does not exist at the specified path relative to `rootPath`, the `rootPath` itself is incorrect, or the default `index` file (`index.html`) is missing.

fix Verify that the `rootPath` option points to the correct directory containing your static files. Ensure that the requested file (or the file specified in `templates.index`) actually exists within that directory and that file permissions allow access.
```
ReferenceError: require is not defined in ES module scope
```
cause You are attempting to use the `require` function to import `static-server` within an ECMAScript (ESM) module context (e.g., in a file where `"type": "module"` is set in your `package.json`).

fix Convert your project or the specific file to use CommonJS modules (remove `"type": "module"` from `package.json` or rename the file to `.cjs`), or use a different static server solution that supports ESM imports.

Warnings

breaking This package is **abandoned** and has not received updates or security patches for several years (last commit 4+ years ago, last release 8+ years ago). It should not be used for new projects or in any environment where security or long-term stability is a concern.
Fix: Consider actively maintained alternatives like `serve`, `http-server`, or a lightweight Express setup for serving static files.
gotcha This server is **NOT for production use**. The README explicitly states, 'Can I use this project in production environments? Obviously not.' and 'Is this server ready to receive thousands of requests? Preferably not.' It lacks performance optimizations, security features, and robustness required for public-facing or high-traffic applications.
Fix: For production, use robust web servers like Nginx, Apache, Caddy, or a production-ready Node.js framework's static file serving capabilities.
gotcha This server is designed **exclusively for static file serving**. It cannot execute or serve dynamic content generated by server-side scripting languages (PHP, Ruby, Python, etc.) or Node.js application logic.
Fix: If dynamic content is required, you must integrate this with a separate application server or use a full-fledged web server that supports your desired backend technology.
gotcha By default, `static-server` will **not follow symbolic links** (`symlinks`) and will respond with a `404 Not Found` error if a requested file is a symlink. This can be confusing if your project uses symlinks to organize assets.
Fix: To enable symlink following, you must explicitly set the `followSymlink: true` option when initializing the `StaticServer` instance: `new StaticServer({ ..., followSymlink: true })`.

Install

npm install static-server npm
yarn add static-server yarn
pnpm add static-server pnpm

Imports

StaticServer
wrong:
```
import StaticServer from 'static-server';
```
correct:
```
var StaticServer = require('static-server');
```
This package is CommonJS-only and does not provide an ESM export. Attempting to use `import` syntax will result in a runtime error in an ES module environment.

Quickstart

This quickstart initializes and starts a static HTTP server on port 1337, serving files from the current directory. It demonstrates basic event listeners for requests and responses, and explicitly enables CORS and symlink following. A temporary `index.html` is created for immediate testing.

var StaticServer = require('static-server');
var server = new StaticServer({
  rootPath: '.',            // required, the root of the server file tree
  port: 1337,               // required, the port to listen
  name: 'my-http-server',   // optional, will set "X-Powered-by" HTTP header
  host: '127.0.0.1',        // optional, defaults to any interface (use '127.0.0.1' for local only)
  cors: '*',                // optional, defaults to undefined, '*' allows all origins
  followSymlink: true,      // optional, defaults to a 404 error if not true
  templates: {
    index: 'index.html',    // optional, defaults to 'index.html'
    notFound: '404.html'    // optional, defaults to undefined
  }
});

server.start(function () {
  console.log('Server listening to', server.port);
  console.log('Serving files from', server.rootPath);
  // Create a dummy index.html for demonstration
  require('fs').writeFileSync('index.html', '<h1>Hello from static-server!</h1>');
  console.log('Created a temporary index.html. Access at http://' + server.host + ':' + server.port);
});

server.on('request', function (req, res) {
  // Log basic request info
  console.log(`Request for ${req.path} took ${req.elapsedTime}`);
});

server.on('response', function (req, res, err, file, stat) {
  // Note: the response has already been sent at this point
  if (err) {
    console.error(`Error serving ${req.path}: ${err.message}`);
  } else if (file) {
    console.log(`Served ${file} with status ${res.status}`);
  }
});

view raw JSON →