Registry / http-networking / hono-geo-middleware

hono-geo-middleware

JSON →
library0.1.2jsnpmunverified

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.

http-networkingweb-framework
npm install hono-geo-middleware
github ↗package ↗
INSTALL
IMPORT
SIG · HONO-GEO-MIDDLEWAR
H
hono-geo-middleware
http-networkingjavascriptv0.1.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

GeoMiddleware
✓ import { GeoMiddleware } from 'hono-geo-middleware';
✗ const { GeoMiddleware } = require('hono-geo-middleware');
Primarily designed for modern ESM environments, compatible with Hono's typical usage in serverless functions.
getGeo
✓ import { getGeo } from 'hono-geo-middleware';
✗ const getGeo = require('hono-geo-middleware').getGeo;
Used to retrieve the extracted geo information from the Hono context after the middleware has run.
Context
✓ import { Context } from 'hono';
When defining custom extractors, the `Context` type needs to be imported directly from 'hono'.

Initializes a Hono application, applies the GeoMiddleware to all routes, and provides an endpoint to retrieve the extracted geolocation data.

import { Hono } from 'hono'; import { GeoMiddleware, getGeo } from 'hono-geo-middleware'; const app = new Hono(); // Apply the GeoMiddleware to all routes app.use('/*', GeoMiddleware()); // Define a route to expose the extracted geo information app.get('/geo', (c) => { const geoData = getGeo(c); if (geoData) { return c.json(geoData); } else { return c.json({ message: 'Geolocation data not available' }, 404); } }); // Example of a root route app.get('/', (c) => c.text('Hello Hono! Geo data available at /geo')); export default { fetch: app.fetch };
Debug
Known issues
breakingAs 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.
fix
Always review the changelog when updating minor versions and pin exact versions in production environments to prevent unexpected breakage.
affects: <1.0.0
gotchaThe 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.
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')`.
affects: >=0.1.0
gotchaProcessing and storing geolocation data carries significant privacy implications (e.g., GDPR, CCPA). The middleware extracts the data but does not provide any compliance mechanisms.
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.
affects: >=0.1.0
gotchaWhen 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.
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.
affects: >=0.1.0
Errors
Common errors & fixes
Cannot find module 'hono-geo-middleware'
The package has not been installed or there is a mismatch in module resolution for ESM.
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';`
TypeError: Cannot read properties of undefined (reading 'ip')
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.
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;`
Cannot find name 'Context'
When defining a `customExtractor` in TypeScript, the `Context` type from Hono needs to be explicitly imported.
fix
Add `import { Context } from 'hono';` to the top of your TypeScript file where the custom extractor is defined.
Upgrade
Version history
0.1.2latest on npm
Audit
Dependencies
honorequiredPeer dependency, as this is a middleware for the Hono framework.
Agent activity
6 hits · last 30 days
node
6
Resources
githubhttps://github.com/ktkongtong/hono-geo-middleware ↗
packagehttps://www.npmjs.com/package/hono-geo-middleware ↗