Registry / devops / bare-server-node

bare-server-node

library2.0.3jsnpmunverified

A Node.js implementation of the TompHTTP bare server specification for creating proxy servers that communicate with backend HTTP servers via WebSockets and fetch. Current stable version 2.0.3, released periodically via GitHub. Key differentiators: supports HTTP, WebSocket, and blob responses; designed for browser-based proxy frontends like Ultraviolet. Breaking v2 changes include a completely new API and CLI. Requires Node 18+.

devops

npm install bare-server-node

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BARE-SERVER-NODE

bare-server-node

devopsjavascriptv2.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

BareServer

✓ import { BareServer } from '@tomphttp/bare-server-node'

✗ const BareServer = require('@tomphttp/bare-server-node')

ESM-only since v2. Use dynamic import for CJS.

createBareServer

✓ import { createBareServer } from '@tomphttp/bare-server-node'

✗ import createBareServer from '@tomphttp/bare-server-node'

Default export removed in v2. Use named export.

BareServerConfig

✓ import type { BareServerConfig } from '@tomphttp/bare-server-node'

TypeScript type import, available for configuration objects.

Creates a Bare server instance with error logging and local IP blocking, integrates with Node HTTP server for routing requests and upgrades.

// Create a simple Bare server import http from 'node:http'; import { createBareServer } from '@tomphttp/bare-server-node'; const bare = createBareServer('/bare/', { logErrors: true, localAddress: undefined, blockLocal: true, }); const server = http.createServer(); server.on('request', (req, res) => { if (bare.shouldRoute(req)) { bare.routeRequest(req, res); } else { res.writeHead(400); res.end('Not using Bare'); } }); server.on('upgrade', (req, socket, head) => { if (bare.shouldRoute(req)) { bare.routeUpgrade(req, socket, head); } else { socket.end(); } }); server.listen(8080, () => { console.log('Bare server running on http://localhost:8080/'); });

Debug

Known issues

breakingv1 classes (like BareServer) are not available in v2; all functionality is exposed via the createBareServer function.

fix

Use createBareServer() and check routes manually; see upgrade guide.

affects: >=2.0.0

deprecatedThe 'requestListener' and 'upgradeListener' options from v1 are deprecated. You must manually attach to the http server events.

fix

Remove options and listen on server events as shown in quickstart.

affects: >=2.0.0

gotchaThe default export was removed in v2; only named exports exist.

fix

Use `import { createBareServer } from '@tomphttp/bare-server-node'` instead of default import.

affects: >=2.0.0

breakingNode.js 18+ is required. v1 supported Node 14+.

fix

Upgrade Node.js to version 18 or later.

affects: >=2.0.0

gotchaThe 'ipaddr.js' package used for local IP blocking is not included by default; install it separately if using `blockLocal: true`.

fix

Install ipaddr.js: `npm install ipaddr.js`

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'ipaddr.js'

Missing optional dependency when blockLocal is enabled.

fix

Run `npm install ipaddr.js` or set blockLocal: false.

TypeError: createBareServer is not a function

Attempting to use default import instead of named import in v2.

fix

Use `import { createBareServer } from '@tomphttp/bare-server-node'`

Error [ERR_INVALID_ARG_TYPE]: The 'listener' argument must be of type function

Passing options to HTTP server creation that expect listener.

fix

Do not pass options to http.createServer(); use server.on('request', ...) manually.

WebSocket connection failed: Unexpected response code: 400

Bare upgrade handler not properly attached; upgrade event not routed.

fix

Ensure you listen on the 'upgrade' event of the server and call bare.routeUpgrade for matching requests.

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

commanderoptionalCLI argument parsing

ipaddr.jsoptionalIP address validation in `blockLocal` mode

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/tomphttp/bare-server-node ↗

packagebare-server-node ↗

homepagehttps://github.com/tomphttp ↗