Servez Library

2.11.0 verified Thu Apr 23 auth: no javascript

Servez-lib, currently at version 2.11.0, is a minimalist HTTP/HTTPS server library primarily designed for internal use within the author's related projects, `servez-cli` and the `servez` web application. It provides basic static file serving capabilities with configurable ports and root directories, including support for index files and logging. The library is explicitly not intended for external consumption or extension by third-party developers; its maintainer strongly recommends copying its source code directly into projects rather than establishing a package dependency. While it offers a simple way to create a local development server, its release cadence and API stability are not managed with external users in mind, making it an unsuitable choice for general-purpose library development. It offers core functionalities like serving index files and basic request handling through a straightforward API.

Common errors

error Error: listen EADDRINUSE: address already in use :::8080 ↓

cause Another process on your machine is already using the specified port (e.g., 8080).

fix

Change the port option in your createServez configuration to an unused port (e.g., 3000, 8000), or identify and terminate the conflicting process.

error Error: ENOENT: no such file or directory, stat '/path/to/nonexistent/root' ↓

cause The `root` directory specified in the server options does not exist on your file system.

fix

Ensure the directory specified by the root option exists. Create it if necessary before starting the server, or correct the path if it's misspelled.

error When accessing the server, I see a directory listing instead of my index.html page. ↓

cause The `index` option might not be correctly configured, or the specified index file (e.g., `index.html`) is not present in the `root` directory.

fix

Set the index option in createServez to the name of your desired index file (e.g., index: 'index.html') and verify that this file exists directly within the root directory you are serving.

Warnings

breaking The author explicitly states this library is not intended for external use or extension by third parties; instead, it's recommended to copy the source code directly into your project. Treating it as a general-purpose library will likely lead to unexpected breaking changes, lack of support, or unaddressed issues. ↓

fix Fork or copy the relevant source code files from `servez-lib` into your project, or choose a different, externally-maintained HTTP server library designed for public consumption and extension.

gotcha API stability is not guaranteed for external consumers. Changes may be introduced without strict adherence to semantic versioning principles for third-party integrations, as the library primarily serves internal projects by the same author. ↓

fix Do not rely on `servez-lib` for long-term external API stability. Any version update should be treated as potentially introducing breaking changes for third-party usage.

gotcha The library is primarily designed for CommonJS (CJS) environments. While it can be imported in ESM projects using default import syntax, direct named ESM imports or explicit `package.json` `type: "module"` configurations might not be fully supported or tested for all functionalities. ↓

fix Prefer CommonJS `require()` for maximum compatibility. If using ESM, use `import createServez from 'servez-lib';` and thoroughly test your application, especially for advanced features.

Install

npm install servez-lib

yarn add servez-lib

pnpm add servez-lib

Imports

createServez
wrong
```
import { createServez } from 'servez-lib';
```
correct
```
const createServez = require('servez-lib');
```
The library primarily exports a single function, `createServez`, using CommonJS `module.exports`. Named ESM imports (`import { ... }`) will not work directly. The author strongly advises against using this library as an external dependency; consider copying its source code instead.
createServez (ESM import)
wrong
```
const createServez = require('servez-lib'); // In an ESM module file
```
correct
```
import createServez from 'servez-lib';
```
While `servez-lib` is a CommonJS package, Node.js allows default imports for CJS modules within ESM contexts. Ensure your project is configured for ESM if using this syntax (e.g., `"type": "module"` in package.json).
Types
```
// No dedicated TypeScript types are officially published or maintained for external use.
```
As `servez-lib` is not intended for third-party consumption, it does not ship with explicit TypeScript declaration files. Users requiring type safety would need to create their own declaration files or rely on inferred types if using TypeScript.

Quickstart

This example demonstrates how to initialize and start a basic HTTP server using `servez-lib` to serve static files from a 'public' directory, handling graceful shutdown.

const createServez = require('servez-lib');
const path = require('path');
const fs = require('fs');

const port = process.env.PORT ?? 8080;
const rootDir = path.join(__dirname, 'public');
const indexFile = 'index.html';

// Ensure the 'public' directory exists and contains an index.html for demonstration
if (!fs.existsSync(rootDir)) {
  fs.mkdirSync(rootDir, { recursive: true });
}
if (!fs.existsSync(path.join(rootDir, indexFile))) {
  fs.writeFileSync(path.join(rootDir, indexFile), `<!DOCTYPE html>\n<html lang="en">\n<head>\n    <meta charset="UTF-8">\n    <meta name="viewport" content="width=device-width, initial-scale=1.0">\n    <title>Servez Quickstart</title>\n</head>\n<body>\n    <h1>Hello from servez-lib!</h1>\n    <p>This page is served from the '${path.basename(rootDir)}' directory.</p>\n    <p>Server running on port ${port}.</p>\n</body>\n</html>`);
}

async function startServer() {
  try {
    const serverOptions = {
      port: port,
      root: rootDir,
      index: indexFile,
      log: true
    };

    const server = await createServez(serverOptions);
    console.log(`Servez server started successfully.`);
    console.log(`Serving files from: ${server.root}`);
    console.log(`Access at: http://localhost:${server.port}`);

    process.on('SIGINT', async () => {
      console.log('\nShutting down Servez server...');
      await server.kill();
      console.log('Servez server shut down.');
      process.exit(0);
    });

  } catch (error) {
    console.error('Failed to start Servez server:', error);
    process.exit(1);
  }
}

startServer();