Registry / http-networking / super-simple-web-server

super-simple-web-server

library1.1.4jsnpmunverified

Super Simple Web Server (super-simple-web-server) is a lightweight Node.js CLI utility designed for quickly serving static files via HTTP and HTTPS on localhost, primarily intended for development and testing purposes. Currently at version 1.1.4, with its last major update in March 2021, the package is in a maintenance state, fulfilling its specific niche without active feature development or a regular release cadence. A key feature is the inclusion of pre-generated, self-signed SSL certificates for HTTPS support, explicitly noted to be unsuitable for production environments and set to expire on June 6, 2028. It distinguishes itself by offering a "fire-and-forget" setup via `npm start` with optional command-line arguments for web root and custom CommonJS middleware, making it ideal for rapid prototyping or isolated local development without complex server configurations. While primarily a CLI tool, it also exposes a programmatic `startServer` function for more controlled integration within Node.js applications.

http-networking web-framework

npm install super-simple-web-server

github ↗package ↗

INSTALL

IMPORT

SIG · SUPER-SIMPLE-WEB-S

super-simple-web-server

http-networkingjavascriptv1.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer

✓ const { startServer } = require('super-simple-web-server');

✗ import { startServer } from 'super-simple-web-server';

The primary programmatic interface, `startServer`, is exposed as a CommonJS named export. Direct ESM `import` is not supported for this function as the package itself does not define `"type": "module"` in its `package.json`.

Full Module Object

✓ const ssws = require('super-simple-web-server'); ssws.startServer(process.cwd(), null, { httpPort: 3000, httpsPort: 3001 });

It is possible to `require` the entire module object, with the `startServer` function available as a property. This is a standard CommonJS pattern.

Middleware Function

✓ module.exports = (app) => { app.use((req, res, next) => { console.log('Middleware activated for:', req.url); next(); }); // Example: Add a custom route app.get('/hello', (req, res) => res.send('Hello from custom middleware!')); };

✗ export default (app) => { /* ... */ };

Custom middleware files, which are loaded by the `super-simple-web-server` instance, must use CommonJS `module.exports` to expose a function that accepts the Express `app` instance. ESM `export` syntax is not supported for these middleware files.

Demonstrates installation, basic server startup, serving from a specified directory, adding custom CommonJS middleware, and configuring ports via environment variables.

npm install super-simple-web-server # To serve files from the current directory on default ports (HTTP 3000, HTTPS 3001) npm start # To serve files from a specific directory, e.g., './public' npm start ./public # Create a middleware.js file: # // middleware.js # module.exports = (app) => { # app.get('/api/data', (req, res) => res.json({ message: 'Data from API', timestamp: Date.now() })); # }; # To serve files from './public' with custom middleware from './middleware.js' npm start ./public ./middleware.js # To change default ports, e.g., HTTP on 8080, HTTPS on 8443 SSWS_HTTP_PORT=8080 SSWS_HTTPS_PORT=8443 npm start

super-simple-web-server --version

Debug

Known issues

gotchaThis package includes self-signed SSL certificates for HTTPS support that will expire on June 6, 2028. These certificates are for development convenience ONLY and are explicitly NOT suitable for production use due to security risks.

fix

For production, use a robust web server like Nginx or Apache, or a Node.js framework (e.g., Express) with properly managed and renewed certificates from a trusted Certificate Authority.

affects: >=1.0.0

gotchaThe server's `index.js` explicitly states 'Don't use this for production'. It is designed for simplicity and quick local development, lacking production-grade security, performance, and monitoring features.

fix

Always use battle-tested, feature-rich server solutions for production deployments. Consider `http-server` or `local-web-server` for more robust static file serving, or a full-fledged framework like Express directly for more complex applications.

affects: >=1.0.0

gotchaCustom middleware files must strictly use CommonJS `module.exports`. Attempting to use ES Modules (`export default` or named `export`) in middleware files will result in runtime errors.

fix

Ensure your middleware file exports its function using `module.exports = (app) => { /* ... */ };` and not ESM syntax. The package's internal `require` mechanism expects CommonJS.

affects: >=1.0.0

gotchaBy default, the server binds to `127.0.0.1` (localhost). To bind to other available IP addresses on your machine, you must modify `index.js` directly by setting `USE_LOCALHOST = false`. This is not configurable via CLI arguments or environment variables.

fix

To serve on a different IP (e.g., for network access), fork the repository or manually edit the `index.js` file in your `node_modules/super-simple-web-server` directory (though not recommended for maintainability) to set `USE_LOCALHOST = false`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: listen EADDRINUSE: address already in use :::3000

The default HTTP port (3000) or HTTPS port (3001) is already in use by another application on your system.

fix

Specify different ports using environment variables: `SSWS_HTTP_PORT=8080 SSWS_HTTPS_PORT=8443 npm start`.

Error: Cannot find module 'path/to/some/middleware'

The path provided for the middleware file is incorrect or the file does not exist at the specified location.

fix

Verify the absolute or relative path to your middleware file. Ensure the file exists and is accessible from where you run `npm start`.

TypeError: app.use is not a function

This error typically occurs within a custom middleware file if the `app` object (the Express application instance) is not correctly received or used, or if the middleware file does not export a function in the expected CommonJS format.

fix

Ensure your middleware file has `module.exports = (app) => { /* ... */ };` and that `app` is correctly passed and used within your function (e.g., `app.use(...)`, `app.get(...)`).

Upgrade

Version history

1.1.4latest on npm

Audit

Dependencies

expressrequiredCore web server framework used internally to handle HTTP/HTTPS requests and serve static files.

osrequiredUtilized for detecting network interfaces when `USE_LOCALHOST` is set to false, to find available IP addresses on the machine.

http-shutdownrequiredProvides graceful shutdown capabilities for the HTTP/HTTPS servers.

commanderrequiredPowers the command-line interface, parsing arguments for web root, middleware, and other options.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/garris/superSimpleExpressServer ↗

packagehttps://www.npmjs.com/package/super-simple-web-server ↗