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.
PixlServer
✓ const PixlServer = require('pixl-server');
✗ import PixlServer from 'pixl-server';
The core server class. Pixl-server is a CommonJS module and primarily uses `require()` for module loading.
WebServerComponent
✓ const WebServer = require('pixl-server-web');
✗ import { WebServer } from 'pixl-server-web';
Example of loading a component module. Components are typically required and passed directly into the `components` array during server instantiation.
APIComponent
✓ require('pixl-server-api')
✗ import PixlServerAPI from 'pixl-server-api';
Illustrates the pattern for including any of the many available `pixl-server-*` component modules in the server's `components` array. No variable assignment is strictly needed if directly within the array.
This quickstart demonstrates how to initialize a Pixl-Server instance, integrate the `pixl-server-web` component to serve static files, and handle graceful shutdown. It sets up a basic web server listening on port 8080, serving an 'index.html' from a local 'www' directory.
const PixlServer = require('pixl-server');
const path = require('path');
const fs = require('fs');
// Create dummy directories for demonstration
const logDir = path.join(__dirname, 'log');
const htdocsDir = path.join(__dirname, 'www');
if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
if (!fs.existsSync(htdocsDir)) fs.mkdirSync(htdocsDir, { recursive: true });
fs.writeFileSync(path.join(htdocsDir, 'index.html'), '<h1>Hello from Pixl-Server!</h1>');
let server = new PixlServer({
__name: 'MyWebServer',
__version: "1.0.50",
config: {
"log_dir": logDir, // Use local log directory
"debug_level": 9,
"WebServer": {
"http_port": 8080, // Use a non-privileged port
"http_htdocs_dir": htdocsDir, // Use local htdocs directory
"http_ip_address": "127.0.0.1" // Explicitly bind to localhost
}
},
components: [
require('pixl-server-web')
]
});
server.startup( function(err) {
if (err) {
console.error("Server startup failed:", err);
process.exit(1);
}
console.log(`MyWebServer v${server.__version} started on http://127.0.0.1:8080`);
console.log(`Serving static files from: ${htdocsDir}`);
console.log("Press Ctrl+C to stop the server.");
// Handle graceful shutdown
process.on('SIGINT', () => {
console.log("\nShutting down server...");
server.shutdown(() => {
console.log("Server shut down gracefully.");
process.exit(0);
});
});
} );
Debug
Known issues
gotchaThe order of components in the `components` array matters. Components that depend on others (e.g., `pixl-server-api` depends on `pixl-server-web`) must be listed after their dependencies to ensure proper initialization.fixArrange components in the `components` array according to their dependencies, ensuring foundational components are listed first.
affects: >=1.0.0
gotchaConfiguration can be overridden by multiple sources (config files, command-line arguments, environment variables). Understanding this hierarchy is crucial to avoid unexpected behavior, as settings can be silently overwritten.fixReview the configuration documentation to understand the precedence of different config sources. Use debug logging (`debug_level: 9`) to inspect the final merged configuration.
affects: >=1.0.0
gotchaA basic Pixl-Server instance without any components will not perform any useful tasks. Developers must explicitly `require()` and add components to the `components` array to extend functionality.fixAlways include relevant components (e.g., `pixl-server-web`, `pixl-server-api`) in the server's `components` array based on the desired functionality.
affects: >=1.0.0
gotchaWhen using `pixl-server-web` (or any component binding to a port), listening on privileged ports (below 1024, like 80 or 443) typically requires root privileges. Running Node.js processes as root is a security risk.fixUse a non-privileged port (e.g., 8080) for your server, or use a reverse proxy (like Nginx) to forward requests from privileged ports to your application's non-privileged port.
affects: >=1.0.0
breakingBased on the provided release history and documentation, there are no explicitly documented breaking API changes within the 1.x major version of `pixl-server` itself. Breaking changes primarily apply to specific `pixl-server-*` components or their upstream dependencies.affects: N/A (no known breaking changes in pixl-server 1.x)
Errors
Common errors & fixes
Error: Cannot find module 'pixl-server-web'
A required component module has not been installed via npm.
fixRun `npm install pixl-server-web` (or the specific missing component) in your project directory.
Error: listen EADDRINUSE: address already in use :::8080
The configured port for the server is already in use by another process.
fixChange the `http_port` in your server's configuration to an available port, or stop the conflicting process. For privileged ports (e.g., 80), ensure no other web server is running.
Server starts but web content is not served or 404s for static files.
The `http_htdocs_dir` configuration for `pixl-server-web` is incorrect, or the files are missing/have incorrect permissions.
fixVerify that `http_htdocs_dir` points to the correct absolute path where your static files reside, and ensure the Node.js process has read access to that directory and its contents.
Audit
Dependencies
pixl-server-webrequiredEssential for building HTTP/HTTPS servers, which is a primary use case. Often considered a de-facto standard component for creating functional server daemons.
pixl-server-apioptionalCommonly used for developing JSON REST APIs, which frequently build on top of the pixl-server-web component.
pixl-server-pooloptionalUseful for offloading CPU-intensive tasks to worker processes, often integrated with pixl-server-web for robust web service scaling.