{"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,"search_vec":"'2.0.1':37 '404':132 'access':142 'api':86 'appear':39 'associ':97 'base':109 'built':22 'cadenc':61 'callback':108,122 'callback-bas':107 'commonj':49 'complex':126 'current':34,66 'defin':88 'design':47,113 'differenti':104 'direct':116 'environ':50 'error':110,135 'exampl':57 'explicit':130 'featur':80 'focus':74 'found':134 'frequent':79 'handl':111 'handler':101,146 'hash':2,6,27 'histor':69 'http':1,5,20,26,120,152 'http-hash':25 'http-hash-rout':4 'implement':154 'includ':92 'indic':51 'integr':115 'introduc':124 'isn':62 'javascript':155 'key':103 'lightweight':10 'make':147 'manag':131 'match':31 'matur':44 'middlewar':127 'minimalist':151 'modul':21 'nativ':19 'node.js':17,118 'packag':28,45 'paramet':93,144 'pattern':30,71,91 'primarili':46 'provid':83,137 'publish':64 'rather':77 'releas':60 'request':100 'requir':54 'rout':14,89 'router':3,7 'server':12,121 'server-sid':11 'servic':153 'side':13 'simpl':85 'specif':59,112 'splat':95 'stabil':76 'stabl':43 'stack':128 'structur':139 'suggest':72 'suitabl':149 'syntax':55 'updat':81 'upon':23 'url':143 'usag':70 'use':90 'util':15 'version':36,67 'way':140 'within':145 'without':123","created_at":"2026-04-23T17:47:37.051438+00:00","updated_at":"2026-04-23T17:47:37.051438+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Matt-Esch/http-hash-router","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/http-hash-router","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-22","install_tag":null}}