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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
static.Server
✓ const static = require('node-static');
const fileServer = new static.Server('./public');
✗ import { Server } from 'node-static';
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
✓ fileServer.serve(request, response);
✗ fileServer.serve(request, response, next);
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
✓ fileServer.serveFile('/error.html', 404, {}, request, response);
✗ 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.
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');
});
Debug
Known issues
breakingOutdated 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.fixThis 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.
affects: >=0.7.11 (when used with modern Node.js versions)
breakingLack 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.fixProjects configured for ES Modules must either use `require()` (if compatible with their setup) or, preferably, migrate to an ESM-compatible static file server.
affects: >=0.7.11 (in ESM projects)
gotchaAbandoned 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.fixAvoid using `node-static` in new projects or existing projects requiring security patches. Migrate to actively maintained alternatives.
affects: >=0.7.11
gotchaManual 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.fixImplement robust, centralized error handling around `fileServer.serve` calls, or migrate to a framework that provides integrated error handling.
affects: >=0.7.11
deprecatedOutdated 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.fixFor any project requiring current Node.js support, it's strongly advised to use a different, actively maintained static file serving library.
affects: >=0.7.11 (when used with modern Node.js versions)
Errors
Common errors & fixes
Error: Cannot find module 'node-static'
The package is not installed or the `require` path is incorrect.
fixRun `npm install node-static` in your project directory. Ensure `require('node-static')` is correctly spelled and located. TypeError: request.addListener is not a function
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.
fixThis 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
The `static` variable was not properly assigned or is out of scope. This often happens if `require('node-static')` is omitted or placed incorrectly.
fixEnsure `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.
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.
fixIf 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.
Audit
Dependencies
No dependency data recorded yet.