{"id":17681,"library":"hono-geo-middleware","title":"Hono Geo Middleware","description":"The `hono-geo-middleware` package provides a specialized Hono middleware for extracting geographical location data from incoming HTTP requests. It is designed to work across various serverless environments, including Cloudflare Workers, Vercel, Netlify Edge Functions, and AWS CloudFront/Lambda@Edge, by intelligently parsing platform-specific headers and context objects. The middleware normalizes this data into a consistent `Geo` interface, offering details like IP address, city, country, country code, and timezone. Currently at version 0.1.2, the package is in its early stages of development, suggesting a potentially frequent release cadence for enhancements and bug fixes. Its primary differentiator is simplifying geo-IP data access within Hono applications, abstracting the complexities of diverse serverless runtime environments and supporting custom extraction logic.","status":"active","version":"0.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/ktkongtong/hono-geo-middleware","tags":["javascript","hono","middleware","geo","hono-middleware","typescript"],"install":[{"cmd":"npm install hono-geo-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add hono-geo-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add hono-geo-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, as this is a middleware for the Hono framework.","package":"hono","optional":false}],"imports":[{"note":"Primarily designed for modern ESM environments, compatible with Hono's typical usage in serverless functions.","wrong":"const { GeoMiddleware } = require('hono-geo-middleware');","symbol":"GeoMiddleware","correct":"import { GeoMiddleware } from 'hono-geo-middleware';"},{"note":"Used to retrieve the extracted geo information from the Hono context after the middleware has run.","wrong":"const getGeo = require('hono-geo-middleware').getGeo;","symbol":"getGeo","correct":"import { getGeo } from 'hono-geo-middleware';"},{"note":"When defining custom extractors, the `Context` type needs to be imported directly from 'hono'.","symbol":"Context","correct":"import { Context } from 'hono';"}],"quickstart":{"code":"import { Hono } from 'hono';\nimport { GeoMiddleware, getGeo } from 'hono-geo-middleware';\n\nconst app = new Hono();\n\n// Apply the GeoMiddleware to all routes\napp.use('/*', GeoMiddleware());\n\n// Define a route to expose the extracted geo information\napp.get('/geo', (c) => {\n  const geoData = getGeo(c);\n  if (geoData) {\n    return c.json(geoData);\n  } else {\n    return c.json({ message: 'Geolocation data not available' }, 404);\n  }\n});\n\n// Example of a root route\napp.get('/', (c) => c.text('Hello Hono! Geo data available at /geo'));\n\nexport default {\n  fetch: app.fetch\n};","lang":"typescript","description":"Initializes a Hono application, applies the GeoMiddleware to all routes, and provides an endpoint to retrieve the extracted geolocation data."},"warnings":[{"fix":"Always review the changelog when updating minor versions and pin exact versions in production environments to prevent unexpected breakage.","message":"As of version 0.1.2, the package is in early development. Minor version updates may introduce breaking changes to the `Geo` interface, middleware options, or extraction logic without strict adherence to semantic versioning for non-major releases.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Implement robust error handling and fallback logic when consuming geo data, checking for `undefined` or null values for specific properties. For example: `c.json(getGeo(c)?.countryCode ?? 'unknown')`.","message":"The availability and accuracy of geolocation data are highly dependent on the hosting serverless environment, client's network configuration, and specific headers provided. Not all fields in the `Geo` interface may be populated for every request.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Developers are solely responsible for ensuring their use of geolocation data complies with all applicable privacy laws and regulations, including obtaining user consent where required.","message":"Processing and storing geolocation data carries significant privacy implications (e.g., GDPR, CCPA). The middleware extracts the data but does not provide any compliance mechanisms.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Carefully consider the order of extractors, placing general or less specific ones before more precise or custom ones if overriding is desired, or vice-versa if specific extractors should take precedence.","message":"When using multiple extractors, especially custom ones, the order of `extractors` in the `GeoMiddleware` configuration matters. Later extractors may overwrite data provided by earlier ones if they target the same fields.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Install the package using your package manager: `npm install hono-geo-middleware` or `yarn add hono-geo-middleware`. For Deno, use the `esm.sh` import URL: `import { GeoMiddleware } from 'https://esm.sh/hono-geo-middleware';`","cause":"The package has not been installed or there is a mismatch in module resolution for ESM.","error":"Cannot find module 'hono-geo-middleware'"},{"fix":"Ensure `app.use('/*', GeoMiddleware())` or a more specific path is correctly applied before the route attempting to read geo data. Also, handle cases where geo data might not be available, e.g., `const ip = getGeo(c)?.ip;`","cause":"The `getGeo(c)` function returned `undefined`, likely because the `GeoMiddleware` was not applied to the current route, or no geo data could be extracted by any configured extractor.","error":"TypeError: Cannot read properties of undefined (reading 'ip')"},{"fix":"Add `import { Context } from 'hono';` to the top of your TypeScript file where the custom extractor is defined.","cause":"When defining a `customExtractor` in TypeScript, the `Context` type from Hono needs to be explicitly imported.","error":"Cannot find name 'Context'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}