Node-Static

Common errors

• Error: Cannot find module 'node-static'

  cause The package is not installed or the `require` path is incorrect.
  fix Run `npm install node-static` in your project directory. Ensure `require('node-static')` is correctly spelled and located.

• TypeError: request.addListener is not a function

  cause This indicates a mismatch between the expected `request` object API in `node-static` and the `http.IncomingMessage` object in newer Node.js versions, where `addListener` might not behave as expected with the `resume()` call.
  fix This problem suggests fundamental incompatibility with modern Node.js stream handling. The most robust fix is to replace `node-static` with an actively maintained static file serving solution compatible with your Node.js version.

• ReferenceError: static is not defined

  cause The `static` variable was not properly assigned or is out of scope. This often happens if `require('node-static')` is omitted or placed incorrectly.
  fix Ensure `const static = require('node-static');` is present and correctly scoped at the top of your file before `static.Server` is used.

• Error [ERR_REQUIRE_ESM]: require() of ES Module [...] not supported.

  cause You are attempting to use `require()` to load `node-static` in an ES Module context, or vice-versa with a modern dependency. `node-static` is CommonJS-only.
  fix If your project is ESM, you cannot directly `require` `node-static`. Consider migrating your project to CommonJS if `node-static` is critical, or, more practically, replace `node-static` with an ESM-compatible static file server.

Warnings

• breaking Outdated Node.js `http` stream API usage: The `request.addListener('end').resume()` pattern is an older method for handling readable streams. In modern Node.js, request streams are typically flowing by default, and this pattern may cause unexpected behavior or hangs.
  Fix: This specific pattern is deeply integrated into `node-static`. For modern Node.js environments, it's recommended to use a contemporary static file serving library like `serve-static` or `express.static` that handles stream management correctly.
• breaking Lack of ESM support: `node-static` is a CommonJS-only package. Attempting to use `import` statements in an ESM context will result in an `ERR_REQUIRE_ESM` error.
  Fix: Projects configured for ES Modules must either use `require()` (if compatible with their setup) or, preferably, migrate to an ESM-compatible static file server.
• gotcha Abandoned Status & Security Risks: The package has not been updated in over eight years. This means it likely contains unpatched security vulnerabilities and is not compatible with modern Node.js features or best practices, posing a significant security risk for production applications.
  Fix: Avoid using `node-static` in new projects or existing projects requiring security patches. Migrate to actively maintained alternatives.
• gotcha Manual Error Handling: Unlike modern web frameworks that integrate error middleware, `node-static` requires explicit `response.writeHead` and `response.end` calls within its error callback. This increases boilerplate and potential for inconsistencies in error responses.
  Fix: Implement robust, centralized error handling around `fileServer.serve` calls, or migrate to a framework that provides integrated error handling.
• deprecated Outdated Node.js Compatibility: The package specifies Node.js `>= 0.4.1`, a version that reached End-of-Life over a decade ago. Using `node-static` with modern Node.js versions may lead to unexpected behavior due to API changes and deprecations.
  Fix: For any project requiring current Node.js support, it's strongly advised to use a different, actively maintained static file serving library.

Install

• npm install node-static npm
• yarn add node-static yarn
• pnpm add node-static pnpm

Imports

• static.Server
  wrong:

  import { Server } from 'node-static';

  correct:

  const static = require('node-static');
  const fileServer = new static.Server('./public');

  This package is CommonJS-only and relies on direct instantiation from the required module. Attempting to use ESM `import` will result in an `ERR_REQUIRE_ESM` error.
• fileServer.serve
  wrong:

  fileServer.serve(request, response, next);

  correct:

  fileServer.serve(request, response);

  The `serve` method takes `request` and `response` objects. Error handling is done via an optional callback or an 'error' event listener, not directly via a `next` middleware function as commonly found in frameworks like Express.
• fileServer.serveFile
  wrong:

  fileServer.serveFile('error.html', 404, request, response);

  correct:

  fileServer.serveFile('/error.html', 404, {}, request, response);

  The path for `serveFile` should be relative to the server's root directory and typically starts with a leading slash. The headers object is a required argument, even if empty.

Quickstart

This quickstart sets up a basic HTTP server using `node-static` to serve files from a `./public` directory. It demonstrates the module's core `Server` instantiation, `serve` method, and basic error handling with an old Node.js `http` stream pattern.

var static = require('node-static');
var http = require('http');

// Create a node-static server instance to serve the './public' folder.
// Ensure a 'public' directory exists in your project root with some static files.
var file = new static.Server('./public', {
    cache: 3600, // Cache files for 1 hour (default)
    headers: {
        'X-Powered-By': 'node-static'
    }
});

http.createServer(function (request, response) {
    // This pattern for handling request 'end' and 'resume' is for older Node.js versions.
    request.addListener('end', function () {
        file.serve(request, response, function (err, result) {
            if (err) {
                console.error("Error serving " + request.url + " - " + err.message);
                // Respond manually to the client if an error occurs
                response.writeHead(err.status || 500, err.headers || { 'Content-Type': 'text/plain' });
                response.end("Error serving file: " + err.message);
            }
        });
    }).resume(); // Important for older Node.js to ensure stream is read
}).listen(8080, function() {
    console.log('node-static server running on http://localhost:8080');
    console.log('Serving files from ./public');
});