{"id":17169,"library":"bare-http1","title":"Bare HTTP/1 Library","description":"bare-http1 is a low-level, native HTTP/1 library for JavaScript, designed for efficient and direct interaction with the HTTP/1 protocol without higher-level abstractions. It provides fundamental primitives for creating HTTP/1 servers and clients, making it suitable for environments where fine-grained control or minimal overhead is paramount. The current stable version is 4.5.6, indicating ongoing maintenance and incremental improvements, as shown by recent patch releases addressing stability. Key differentiators include its 'bare' philosophy, focusing solely on HTTP/1, and its light footprint, often used in conjunction with other 'bare-' ecosystem modules like bare-buffer and bare-url for buffer and URL handling. It ships with TypeScript types, facilitating robust development in TypeScript projects and ensuring type safety.","status":"active","version":"4.5.6","language":"javascript","source_language":"en","source_url":"https://github.com/holepunchto/bare-http1","tags":["javascript","typescript"],"install":[{"cmd":"npm install bare-http1","lang":"bash","label":"npm"},{"cmd":"yarn add bare-http1","lang":"bash","label":"yarn"},{"cmd":"pnpm add bare-http1","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Essential for buffer allocation and manipulation in low-level HTTP message processing.","package":"bare-buffer","optional":false},{"reason":"Used for parsing and constructing URLs within HTTP requests and responses.","package":"bare-url","optional":false}],"imports":[{"note":"Use named import for ESM. For CommonJS, destructure from the `require` result.","wrong":"const { createServer } = require('bare-http1')","symbol":"createServer","correct":"import { createServer } from 'bare-http1'"},{"note":"Similar to `createServer`, use named import for ESM or destructure for CommonJS.","wrong":"const { request } = require('bare-http1')","symbol":"request","correct":"import { request } from 'bare-http1'"},{"note":"The library primarily exposes named exports. When using CommonJS, the `require` call returns an object containing `createServer` and `request`.","wrong":"import http from 'bare-http1'","symbol":"http","correct":"const http = require('bare-http1')"}],"quickstart":{"code":"import { createServer, request } from 'bare-http1';\nimport { Buffer } from 'bare-buffer';\n\nconst server = createServer((req, res) => {\n  console.log(`Server received request: ${req.method} ${req.url}`);\n  res.statusCode = 200;\n  res.setHeader('Content-Type', 'text/plain');\n  res.setHeader('Content-Length', 12);\n  res.write('hello world!');\n  res.end();\n});\n\nserver.listen(0, () => {\n  const { port } = server.address() as { port: number };\n  console.log('Server is bound on port', port);\n\n  const client = request({ port, method: 'GET', path: '/' }, (res) => {\n    console.log(`Client received response: ${res.statusCode}`);\n    const chunks: Buffer[] = [];\n    res.on('data', (data) => chunks.push(Buffer.from(data)));\n    res.on('end', () => {\n      console.log('Client received data:', Buffer.concat(chunks).toString());\n      server.close(() => console.log('Server closed.'));\n    });\n  });\n  client.end();\n});\n\nserver.on('error', (err) => {\n  console.error('Server error:', err);\n});","lang":"typescript","description":"This example demonstrates how to create a basic HTTP/1 server that listens on a random port, then makes a client request to that server, logging the response body. It showcases the core `createServer` and `request` functions for fundamental HTTP/1 communication and includes basic error handling."},"warnings":[{"fix":"Ensure `server.on('error', ...)` and `client.on('error', ...)` listeners are always present in your code to gracefully handle network and protocol errors.","message":"Prior to version 4.5.6, the library had a higher chance of crashing if error handlers were not explicitly set on servers and clients. It's crucial to always attach 'error' event listeners to prevent unhandled exceptions and process exits, especially in production environments.","severity":"gotcha","affected_versions":"<4.5.6"},{"fix":"Be prepared to implement stream processing, header validation, and body parsing logic manually or integrate with other 'bare-' ecosystem modules designed for these tasks.","message":"bare-http1 provides a minimal, low-level API. Users accustomed to higher-level HTTP frameworks (e.g., Node.js `http` module or Express) should be aware that manual handling of request/response streams, headers, and body parsing (e.g., JSON, forms) is often required. There are no built-in middleware or routing capabilities.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For HTTP/2 or HTTP/3 communication, use dedicated libraries or proxies that support those protocols. `bare-http1` is not a drop-in replacement for multi-protocol HTTP stacks.","message":"This library exclusively supports HTTP/1.x. It does not provide built-in support for HTTP/2 or HTTP/3. Attempting to use it with clients or servers expecting newer HTTP versions will likely result in protocol errors or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Choose a different port, ensure previous server instances are closed, or configure the server to listen on port 0 to let the OS assign an available port.","cause":"The specified port is already in use by another application or a previous instance of your server that wasn't properly shut down.","error":"Error: listen EADDRINUSE: address already in use :::<port>"},{"fix":"Verify that the server is running and listening on the correct IP/port, check network connectivity, and ensure no firewalls are blocking the connection.","cause":"The client attempted to connect to a server that was not listening on the specified IP address and port, or a firewall blocked the connection.","error":"Error: connect ECONNREFUSED <ip>:<port>"},{"fix":"Ensure all header-related operations (setting status code, `setHeader()`) are performed *before* any calls to `res.write()` or `res.end()`.","cause":"An attempt was made to modify HTTP headers or call `setHeader()` after the response body has already started being sent (e.g., after `res.write()` or `res.end()` has been called).","error":"ERR_HTTP_HEADERS_SENT: Cannot set headers after they are sent to the client"}],"ecosystem":"npm","meta_description":null}