srvx: Universal Web Standard Server

0.11.15 · active · verified Sun Apr 19

srvx is a modern, zero-dependency HTTP server framework built on Web Standards (Request/Response API), enabling consistent deployment and execution across multiple JavaScript runtimes including Node.js, Deno, and Bun. It currently stands at version 0.11.15, with active development primarily focusing on bug fixes and performance enhancements in its frequent patch releases. A key differentiator is its emphasis on Web Standard APIs, providing a unified programming model regardless of the underlying runtime. It also boasts a full-featured Command Line Interface (CLI) that includes a file watcher, error handling, static file serving, and logging, streamlining the development workflow. srvx aims for close-to-native performance, especially in Node.js environments.

Common errors

```
Error: listen EADDRINUSE: address already in use :::3000
```
cause Another process is currently bound to the specified network port (e.g., 3000), preventing srvx from starting.

fix Change the server's listening port to an available one (e.g., `server.listen(3001)`), or identify and terminate the process that is already using the port.
```
ERR_REQUIRE_ESM
```
cause Attempting to import srvx using CommonJS `require()` syntax (`const srvx = require('srvx')`) in a JavaScript module environment configured for ESM.

fix Update your import statements to use ES module syntax (e.g., `import { createServer } from 'srvx'`). Ensure your project's `package.json` specifies `"type": "module"` or use `.mjs` file extensions for ES Modules.
```
Cannot find module 'srvx' or its corresponding type declarations.
```
cause The 'srvx' package has not been installed, the import path is incorrect, or TypeScript cannot locate its type definition files.

fix Install the package using your package manager (e.g., `npm install srvx`, `pnpm add srvx`, or `yarn add srvx`). If using TypeScript, ensure `tsconfig.json` is correctly configured to include `node_modules/@types`.

Warnings

breaking srvx explicitly requires Node.js version 20.16.0 or higher. Deployments on older Node.js environments will fail to start or encounter runtime errors due to reliance on newer APIs.
Fix: Upgrade your Node.js runtime to version 20.16.0 or newer. Use a version manager like `nvm` to switch or update your Node.js environment.
gotcha As a package in its 0.x.x version series, srvx may introduce breaking changes in minor releases (e.g., 0.11.x to 0.12.x) without adhering strictly to Semantic Versioning, which typically reserves breaking changes for major version increments.
Fix: Exercise caution when upgrading between minor versions. Always review the changelog for potential breaking changes. Consider pinning to exact patch versions (`0.11.15`) or using a lockfile to ensure stability in production environments.
gotcha Beginning with version 0.11.15, `srvx` no longer silently swallows errors originating from `getReader` operations. This means applications that previously had errors silently ignored may now experience unhandled promise rejections or exceptions.
Fix: Implement robust error handling around `getReader` and other asynchronous I/O operations within your srvx handlers to gracefully manage potential failures.
gotcha Since version 0.11.8, srvx performs validation of the `Host` header. Requests with invalid or malformed `Host` headers that might have been processed in earlier versions will now be rejected, which could affect certain proxy setups or custom client implementations.
Fix: Ensure all clients and proxy configurations send valid `Host` headers that conform to HTTP specifications. Debug with detailed logging to identify the source of invalid headers if issues arise.

Install

npm install srvx npm
yarn add srvx yarn
pnpm add srvx pnpm

Imports

createServer
wrong:
```
const { createServer } = require('srvx')
```
correct:
```
import { createServer } from 'srvx'
```
srvx is primarily an ESM-first package; CommonJS 'require' syntax will generally result in ERR_REQUIRE_ESM for named exports.
Server (type)
```
import { Server } from 'srvx'
```
Import the `Server` type for explicit type annotations when working with programmatic server instances in TypeScript.
srvx CLI handler (default export)
```
// my-handler.js
export default {
  fetch(req: Request) {
    return new Response('Hello from CLI handler!');
  },
};
```
When using the `srvx` CLI to serve a file, the file should default export an object containing a `fetch` method, adhering to the Web Standard Request/Response API. No explicit `import` of `srvx` is typically needed within the handler file itself for this usage pattern.

Quickstart

This quickstart demonstrates how to programmatically create and run an srvx server that handles basic routing using Web Standard Request and Response objects. It sets up a health check endpoint and a personalized greeting API, listening on a configurable port.

import { createServer } from 'srvx';

const server = createServer((req: Request) => {
  const url = new URL(req.url);

  if (url.pathname === '/health') {
    return new Response('OK', { status: 200, headers: { 'Content-Type': 'text/plain' } });
  }

  if (url.pathname.startsWith('/api/greet')) {
    const name = url.searchParams.get('name') || 'World';
    return new Response(`Hello, ${name}!`, { headers: { 'Content-Type': 'text/plain' } });
  }

  return new Response(`Welcome to srvx! You accessed: ${url.pathname}\nTry /api/greet?name=Alice or /health`, {
    headers: { 'Content-Type': 'text/plain' },
  });
});

const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;

server.listen(PORT, () => {
  console.log(`srvx server listening on http://localhost:${PORT}`);
  console.log('Test with:');
  console.log(`- curl http://localhost:${PORT}/`);
  console.log(`- curl http://localhost:${PORT}/health`);
  console.log(`- curl "http://localhost:${PORT}/api/greet?name=User"`);
});

view raw JSON →