@addilytics/hono

Hono middleware that records pageviews from the final Context.res. It does not read, clone, or replace the response body.

import { addilytics } from '@addilytics/hono';
import { Hono } from 'hono';

const app = new Hono();
const analytics = addilytics({
	endpoint: 'https://addilytics.example',
	siteKey: 'ak_...'
});

app.use('*', analytics);

Register authentication or context initialization first, Addilytics second, and routes or response-mutating middleware after it. Hono runs Addilytics as an outer layer around later handlers, so it sees the final response after they finish. Relay requests return from Addilytics without running later middleware. Redirects, JSON responses, and server errors are skipped by default.

Only requests dispatched through this Hono app count. A CDN response, prerendered file, client-side route change without an HTML request, or browser back-forward cache restore bypasses the middleware.

Custom events

The middleware carries a typed track() method.

app.post('/signup', async (context) => {
	await analytics.track(context, 'signup', {
		props: { source: 'pricing' }
	});
	return context.body(null, 204);
});

track() uses the same bot filtering and identity rules as the core client.

Identity and background delivery

Use user when identity lives in a Hono variable or binding.

const analytics = addilytics({
	endpoint: 'https://addilytics.example',
	siteKey: 'ak_...',
	user: (context) => context.get('userId')
});

app.use('*', authMiddleware);
app.use('*', analytics);

The user resolver can read context.get() only when an earlier middleware sets that value. A resolver that reads the raw request can stay inside the Addilytics options.

Hono does not expose a portable client-address API. Supply ip when the deployment runtime keeps the address on a binding, request property, or trusted context value:

const analytics = addilytics({
	endpoint: 'https://addilytics.example',
	siteKey: 'ak_...',
	ip: (context) => context.env.incomingRequestIp
});

The resolver may be async. If it throws, the adapter reports an ip error and records the event without an address. It does not fall back to forwarded headers after a resolver failure. Without an ip resolver, trustProxy: true enables the core client's forwarded-header fallback.

The adapter uses context.executionCtx.waitUntil() on runtimes that provide it. Elsewhere it waits for delivery before the request completes. You can supply waitUntil when a platform exposes its background-task hook somewhere else.

Analytics failures never replace or reject an otherwise successful application response.

Browser navigation modes

Server tracking remains the default. Use hybrid when Hono records the initial document and your client router reports later navigations. Use client when the browser owns every pageview. Client mode keeps custom server events enabled but skips automatic server document capture.

Configure authentication before the analytics middleware, then put routes after it so the relay can use established identity without reaching application handlers:

const analytics = addilytics({
	endpoint: process.env.ADDILYTICS_ENDPOINT!,
	mode: 'hybrid',
	relayPath: '/internal/analytics',
	siteKey: process.env.ADDILYTICS_SITE_KEY!
});

app.use('*', authMiddleware);
app.use('*', analytics);

Hono has no client router, so its browser entry re-exports the generic tracker. Call pageview() after your router commits a navigation, including the initial page:

import { createBrowserTracker } from '@addilytics/hono/browser';

const tracker = createBrowserTracker({
	endpoint: '/internal/analytics',
	mode: 'hybrid'
});

router.afterEach((url) => tracker.pageview(url));

Hybrid mode skips the first browser call because the server owns it. Client mode sends that call. The core tracker deduplicates repeated URLs and ignores hash-only changes unless you set trackHashChanges: true. Applications should also call pageview() with force: true for a persisted pageshow event if back-forward cache restores count as new visits.

The browser sends only a generated event ID, timestamp, pathname, allowlisted campaign query, and referrer. The relay adds trusted server metadata and user identity. It accepts only its exact path and rejects cross-origin or malformed requests. The site key and ingest endpoint stay in server code, and this package does not inject or load an external script.