Simple Command-Line HTTP Server

2.4.0 · active · verified Sun Apr 19

Servez is a straightforward command-line HTTP server designed for local development and learning, serving static files quickly. As of version 2.4.0, it offers zero-configuration defaults but provides a rich set of options for customization, including port selection, directory listing, CORS headers, gzip/brotli compression, and basic authentication. Its primary differentiator is its simplicity and ease of use, aiming to replace tools like `http-server` with a modern, actively maintained alternative. It supports both HTTP and HTTPS (with self-signed or custom certificates) and can display QR codes for easy mobile access. The project appears to have a regular, albeit not fixed, release cadence, driven by user needs and feature enhancements, making it a reliable choice for development server needs.

Common errors

```
servez: command not found
```
cause The `servez` command is not available in your system's PATH.

fix Install it globally via `npm install -g servez` or execute it directly using `npx servez`.
```
ERR_CONNECTION_REFUSED
```
cause The `servez` server is not running, or it's running on a different port/address than you're trying to access.

fix Ensure `servez` is running and check the console output for the correct URL (e.g., `http://localhost:8080` or the next available port). If using `--local`, confirm you're accessing `127.0.0.1`.
```
Access to fetch at 'http://localhost:8080/data.json' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
```
cause Your browser is blocking a cross-origin request because the `servez` server did not send the necessary CORS headers.

fix Start `servez` with the `--cors` option to enable CORS headers: `servez --cors`.
```
NET::ERR_CERT_AUTHORITY_INVALID
```
cause You are using HTTPS (`--ssl`) with a self-signed certificate that your browser does not implicitly trust.

fix For development, you can usually proceed past the browser warning. For a trusted setup, provide your own valid SSL certificate and key files using `--cert <path_to_cert>` and `--key <path_to_key>`.

Warnings

gotcha By default, `servez` serves on all network interfaces (0.0.0.0), making it publicly accessible on your local network. To restrict access only to the local machine, use the `--local` option.
Fix: Always include `--local` if you intend for the server to be accessible only from `127.0.0.1` (localhost).
gotcha When using `--ssl` without specifying `--cert` and `--key` paths, `servez` generates a self-signed (fake) SSL certificate. Browsers will typically warn about this as the certificate is not trusted by a recognized Certificate Authority.
Fix: For secure development, either configure your browser to trust the self-signed certificate, or provide valid, trusted certificates using `--cert` and `--key`.
gotcha If the default port 8080 is already in use, `servez` will automatically scan for and use the next available port. Users might inadvertently connect to a different port than expected.
Fix: Check the server output in the terminal to confirm the exact port being used, or explicitly specify a port with `--port <number>`.
gotcha The `servez` CLI tool requires Node.js to be installed on your system. Using a Node Version Manager (like nvm or nvm-windows) is highly recommended to manage Node.js versions effectively.
Fix: Install Node.js via `nvm` (mac/linux) or `nvm-windows` (windows) before attempting to install or run `servez`.

Install

npm install servez npm
yarn add servez yarn
pnpm add servez pnpm

Imports

servez
wrong:
```
import servez from 'servez';
```
correct:
```
servez [options] [path]
```
This refers to executing the 'servez' command after a global npm installation. It is primarily a CLI tool and not designed for direct programmatic import as a JavaScript module.
npx servez
```
npx servez [options] [path]
```
Using 'npx' allows you to execute 'servez' on-demand without a global installation, ensuring you use the latest version or a specific version by appending '@<version>'.
npm install -g servez
wrong:
```
require('servez').installGlobal();
```
correct:
```
npm install -g servez
```
This command installs the 'servez' executable globally on your system, making it accessible from any directory in your terminal.

Quickstart

Demonstrates how to programmatically start `servez` from a Node.js script, creating a public directory with sample content and serving it on port 8080 with directory listings, CORS, QR code, and local access enabled.

const { spawn } = require('child_process');
const path = require('path');
const fs = require('fs');

const publicDir = path.join(__dirname, 'public');
if (!fs.existsSync(publicDir)) {
  fs.mkdirSync(publicDir);
}
fs.writeFileSync(path.join(publicDir, 'index.html'), '<h1>Hello, Servez from JS!</h1>');
fs.writeFileSync(path.join(publicDir, 'style.css'), 'body { font-family: sans-serif; }');

console.log('Starting servez...');
const servezProcess = spawn('npx', ['servez', publicDir, '--port', '8080', '--dirs', '--cors', '--qr', '--local', '--index'], {
  stdio: 'inherit',
  shell: true // Needed on Windows for npx to be found
});

servezProcess.on('error', (err) => {
  console.error('Failed to start servez process:', err);
});

servezProcess.on('exit', (code) => {
  console.log(`servez process exited with code ${code}`);
});

console.log('Server should be available at http://localhost:8080');
console.log('Press Ctrl+C to stop this script and the servez server.');

view raw JSON →