Super Simple Web Server

Common errors

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

  cause 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'

  cause 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

  cause 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(...)`).

Warnings

• gotcha This 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.
• gotcha The 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.
• gotcha Custom 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.
• gotcha By 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`.

Install

• npm install super-simple-web-server npm
• yarn add super-simple-web-server yarn
• pnpm add super-simple-web-server pnpm

Imports

• startServer
  wrong:

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

  correct:

  const { startServer } = require('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
  wrong:

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

  correct:

  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!'));
  };

  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.

Quickstart

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