{"id":18666,"library":"pixl-server-web","title":"pixl-server-web","description":"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.","status":"active","version":"3.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/jhuckaby/pixl-server-web","tags":["javascript","web","http","https","ssl"],"install":[{"cmd":"npm install pixl-server-web","lang":"bash","label":"npm"},{"cmd":"yarn add pixl-server-web","lang":"bash","label":"yarn"},{"cmd":"pnpm add pixl-server-web","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core framework for which this component is designed","package":"pixl-server","optional":false},{"reason":"Used for class-based inheritance and configuration","package":"pixl-class","optional":true},{"reason":"Performance measurement library used by the request timing features","package":"pixl-perf","optional":true}],"imports":[{"note":"This package is CommonJS-only; ESM import is not supported.","wrong":"import pixlServerWeb from 'pixl-server-web'","symbol":"pixl-server-web","correct":"require('pixl-server-web')"},{"note":"The default export is the package's root module; the constructor is on .PixlServerWeb.","wrong":"const webServer = new(require('pixl-server-web'))()","symbol":"PixlServerWeb","correct":"const webServer = new(require('pixl-server-web').PixlServerWeb)()"},{"note":"Sub-components are accessed via the main module, not separate files.","wrong":"const HttpServer = require('pixl-server-web/http')","symbol":"HttpServer","correct":"const HttpServer = require('pixl-server-web').HttpServer"}],"quickstart":{"code":"const pixlServer = require('pixl-server');\nconst server = new pixlServer();\nserver.start({\n  __main: require('pixl-server-web'),\n  web: {\n    port: 8080,\n    htdocs_dir: '/var/www/html',\n    log_requests: true\n  }\n});\nconsole.log('Server running on http://localhost:8080');","lang":"javascript","description":"Initializes a pixl-server with the web component, serving static files from /var/www/html on port 8080."},"warnings":[{"fix":"Add 'legacy_callback_support: true' to web config.","message":"v3.0.0 removed legacy_callback_support by default; must set config.legacy_callback_support=true if needed.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Set 'log_requests: false' to suppress logs.","message":"v3.0.0 changed default for log_requests from false to true.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Rename config key to 'recent_requests_max'.","message":"config.recent_requests is deprecated; use 'recent_requests_max' instead.","severity":"deprecated","affected_versions":">=2.5.0"},{"fix":"Set proper file permissions or run process with elevated privileges.","message":"When using HTTPS, ensure the cert files are readable by the process user.","severity":"gotcha","affected_versions":"*"},{"fix":"Use require() instead of import.","message":"The package does not support ESM imports; CommonJS only.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure all static files are within htdocs_dir.","message":"Static file paths are relative to htdocs_dir; do not serve parent directories.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run 'npm install pixl-server pixl-server-web'.","cause":"Package not installed or peer dependency pixl-server is missing.","error":"Error: Cannot find module 'pixl-server-web'"},{"fix":"Pass { __main: require('pixl-server-web'), web: {...} } to server.start().","cause":"Incorrect initialization: missing __main configuration.","error":"TypeError: pixlServer.start is not a function"},{"fix":"Change the port in config or kill the process using that port.","cause":"Port 8080 is already in use.","error":"Error: listen EADDRINUSE :::8080"},{"fix":"Send valid JSON with Content-Type: application/json.","cause":"Invalid JSON in POST body.","error":"SyntaxError: Unable to parse JSON from request body"},{"fix":"Verify https_cert_file and https_key_file paths and permissions.","cause":"HTTPS enabled but cert file path is incorrect or unreadable.","error":"Error: SSL certificate not found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}