{"id":17693,"library":"http-hash-router","title":"HTTP Hash Router","description":"http-hash-router is a lightweight server-side routing utility for Node.js's native `http` module, built upon the `http-hash` package for pattern matching. It is currently at version 2.0.1 and appears to be a stable, mature package primarily designed for CommonJS environments, indicated by its `require` syntax in examples. While specific release cadence isn't published, its current version and historical usage patterns suggest a focus on stability rather than frequent feature updates. It provides a simple API to define routes using patterns (including parameters and splats) and associate them with request handlers. A key differentiator is its callback-based error handling, specifically designed to integrate directly into Node.js's HTTP server callback without introducing a complex middleware stack. It explicitly manages `404 Not Found` errors and provides a structured way to access URL parameters within handlers, making it suitable for minimalistic HTTP service implementations.","status":"maintenance","version":"2.0.1","language":"javascript","source_language":"en","source_url":"git://github.com/Matt-Esch/http-hash-router","tags":["javascript"],"install":[{"cmd":"npm install http-hash-router","lang":"bash","label":"npm"},{"cmd":"yarn add http-hash-router","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-hash-router","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for route pattern matching and storage.","package":"http-hash","optional":false},{"reason":"Used to create route handler functions when an object is provided as a handler.","package":"http-methods","optional":true}],"imports":[{"note":"Package is primarily CommonJS (CJS). Direct ESM `import` statements are not officially supported and may require interop configuration.","wrong":"import HttpHashRouter from 'http-hash-router';","symbol":"HttpHashRouter","correct":"const HttpHashRouter = require('http-hash-router');"},{"note":"Routes are defined using the `.set()` method on the router instance, not `.add()` or other common router methods.","wrong":"router.add('/path', handlerFunc);","symbol":"router.set","correct":"router.set('/path', handlerFunc);"}],"quickstart":{"code":"const http = require('http');\nconst HttpHashRouter = require('http-hash-router');\n\nconst router = HttpHashRouter();\n\nrouter.set('/health', function health(req, res) {\n    res.setHeader('Content-Type', 'text/plain');\n    res.end('OK');\n});\n\nrouter.set('/greet/:name', function greet(req, res, opts, cb) {\n    res.setHeader('Content-Type', 'text/plain');\n    res.end(`Hello, ${opts.params.name}!`);\n});\n\nconst server = http.createServer(function handler(req, res) {\n    router(req, res, {}, onError);\n\n    function onError(err) {\n        if (err) {\n            // Custom error serialization and response\n            res.statusCode = err.statusCode || 500;\n            res.setHeader('Content-Type', 'application/json');\n            if (err.type === 'http-hash-router.not-found') {\n                res.end(JSON.stringify({ error: 'Not Found', path: req.url }));\n            } else {\n                res.end(JSON.stringify({ error: err.message || 'Internal Server Error' }));\n            }\n        }\n    }\n});\n\nserver.listen(3000, () => {\n    console.log('Server listening on http://localhost:3000');\n    console.log('Try visiting http://localhost:3000/health and http://localhost:3000/greet/world');\n});","lang":"javascript","description":"Demonstrates setting up a basic HTTP server with `http-hash-router`, defining two routes (one static, one with a parameter), and handling errors including 404s via a callback."},"warnings":[{"fix":"Always pass a callback function as the fourth argument to `router(req, res, opts, onError)` to handle potential errors, including 404 Not Found errors.","message":"The `router` function (`router(req, res, opts, cb)`) explicitly *requires* a callback function as its fourth argument. Failing to provide one will immediately throw an `http-hash-router.expected.callback` exception.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For ESM projects, consider using a CommonJS compatibility layer or bundler to consume this package. Alternatively, explore modern routing libraries built with native ESM support.","message":"This package is designed for CommonJS (CJS) environments and primarily uses `require()`. While it might be usable in an ESM project via compatibility layers, direct `import` statements are not officially supported or demonstrated. Users should anticipate potential interop issues if integrating into modern ESM-only Node.js projects.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your application explicitly handles errors within the callback passed to the router. Convert callback-based handlers to Promises if integrating with an `async/await` codebase.","message":"Error handling is entirely callback-based, meaning errors (including 404 Not Found) are passed to the provided callback function, not thrown or handled by Promises. This contrasts with modern `async/await` patterns.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Always provide a callback as the fourth argument to the `router` function, e.g., `router(req, res, {}, onError);`. This callback will receive any errors, including `NotFoundError` (for 404s), or will be passed to your route handler if no error occurred.","cause":"The main `router` function was invoked without a fourth argument, which must be a callback function for error handling.","error":"http-hash-router.expected.callback (runtime exception)"},{"fix":"Use the CommonJS `require()` syntax: `const HttpHashRouter = require('http-hash-router');` instead of `import HttpHashRouter from 'http-hash-router';`.","cause":"The package is primarily CommonJS (CJS) and its default export might not be directly compatible with ESM `import` syntax without specific Node.js or bundler configuration.","error":"TypeError: HttpHashRouter is not a function (when using import)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}