srvx

library0.11.15jsnpmunverified

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.

web-framework http-networking devops

npm install srvx

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SRVX

srvx

web-frameworkjavascriptv0.11.15

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createServer

✓ import { createServer } from 'srvx'

✗ const { createServer } = require('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.

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"`); });

srvx --version

Debug

Known issues

breakingsrvx 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.

affects: <0.11.0

gotchaAs 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.

affects: >=0.0.0

gotchaBeginning 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.

affects: >=0.11.15

gotchaSince 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.

affects: >=0.11.8

Errors

Common errors & fixes

Error: listen EADDRINUSE: address already in use :::3000

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

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.

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`.

Upgrade

Version history

0.11.15latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/h3js/srvx ↗

packagehttps://www.npmjs.com/package/srvx ↗

homepagehttps://srvx.h3.dev ↗