pixl-server-web

3.0.4 verified Sat Apr 25 auth: no javascript

A web server component for the pixl-server framework, supporting HTTP and HTTPS, static file serving, custom URI handlers, access control, request logging, and performance monitoring. Current stable version is 3.0.4. Release cadence is moderate; breaking changes are rare but documented. Key differentiators: deep integration with pixl-server ecosystem, extensive configuration options, and built-in support for features like compression, keep-alive, and request queuing.

Common errors

error Error: Cannot find module 'pixl-server-web' ↓

cause Package not installed or peer dependency pixl-server is missing.

fix

Run 'npm install pixl-server pixl-server-web'.

error TypeError: pixlServer.start is not a function ↓

cause Incorrect initialization: missing __main configuration.

fix

Pass { __main: require('pixl-server-web'), web: {...} } to server.start().

error Error: listen EADDRINUSE :::8080 ↓

cause Port 8080 is already in use.

fix

Change the port in config or kill the process using that port.

error SyntaxError: Unable to parse JSON from request body ↓

cause Invalid JSON in POST body.

fix

Send valid JSON with Content-Type: application/json.

error Error: SSL certificate not found ↓

cause HTTPS enabled but cert file path is incorrect or unreadable.

fix

Verify https_cert_file and https_key_file paths and permissions.

Warnings

breaking v3.0.0 removed legacy_callback_support by default; must set config.legacy_callback_support=true if needed. ↓

fix Add 'legacy_callback_support: true' to web config.

breaking v3.0.0 changed default for log_requests from false to true. ↓

fix Set 'log_requests: false' to suppress logs.

deprecated config.recent_requests is deprecated; use 'recent_requests_max' instead. ↓

fix Rename config key to 'recent_requests_max'.

gotcha When using HTTPS, ensure the cert files are readable by the process user. ↓

fix Set proper file permissions or run process with elevated privileges.

gotcha The package does not support ESM imports; CommonJS only. ↓

fix Use require() instead of import.

gotcha Static file paths are relative to htdocs_dir; do not serve parent directories. ↓

fix Ensure all static files are within htdocs_dir.

Install

npm install pixl-server-web

yarn add pixl-server-web

pnpm add pixl-server-web

Imports

pixl-server-web
wrong
```
import pixlServerWeb from 'pixl-server-web'
```
correct
```
require('pixl-server-web')
```
This package is CommonJS-only; ESM import is not supported.

PixlServerWeb

wrong

const webServer = new(require('pixl-server-web'))()

correct

const webServer = new(require('pixl-server-web').PixlServerWeb)()

The default export is the package's root module; the constructor is on .PixlServerWeb.

HttpServer

wrong

const HttpServer = require('pixl-server-web/http')

correct

const HttpServer = require('pixl-server-web').HttpServer

Sub-components are accessed via the main module, not separate files.

Quickstart

Initializes a pixl-server with the web component, serving static files from /var/www/html on port 8080.

const pixlServer = require('pixl-server');
const server = new pixlServer();
server.start({
  __main: require('pixl-server-web'),
  web: {
    port: 8080,
    htdocs_dir: '/var/www/html',
    log_requests: true
  }
});
console.log('Server running on http://localhost:8080');