cs_posthog
v1.1.0
Published
PostHog analytics wrapper with custom domain (proxy) support for browser and Next.js
Downloads
11
Readme
cs_posthog
PostHog analytics wrapper with custom domain (proxy) support for browser and Next.js. Single tracker instance, optional host allowlist, UTM capture on pageviews and conversions, and SSR-safe API.
Features
- Custom domain – Point PostHog at your proxy/ingestion domain (e.g.
https://analytics.yoursite.com). - Optional host allowlist – Initialize only when
window.location.hostmatches a given host (e.g.myapp.comorlocalhost:3000). - Single tracker – One shared instance; call
init()once, then usetrackPageView,trackEvent,trackConversion, andidentifyanywhere. - UTM capture –
trackPageView()andtrackConversion()automatically include UTM params from the URL (utm_source,utm_medium,utm_campaign,utm_content,utm_term). - Browser-safe – All methods no-op when
windowis undefined (e.g. during SSR). - Manual pageviews – Default
capture_pageview: falseso you control when to send$pageview(e.g. on route change in Next.js). - Identified-only profiles – Uses
person_profiles: 'identified_only'. - Dev debug – Enables PostHog debug when
NODE_ENV === 'development'.
Installation
npm install cs_posthogUsage
Initialize (once)
Without host check (3 arguments) – init runs on any host:
const { tracker } = require('cs_posthog');
tracker.init(
'YOUR_POSTHOG_API_KEY',
'https://us.i.posthog.com', // or your proxy URL
false // capturePageView: false
);With host check (4 arguments) – init runs only when window.location.host matches:
tracker.init(
process.env.NEXT_PUBLIC_POSTHOG_KEY,
process.env.NEXT_PUBLIC_APP_HOST, // e.g. 'myapp.com' or 'localhost:3000'
'https://us.i.posthog.com',
false
);API key and allowed host should come from the app that uses the package (e.g. env vars).
Track page views
Sends $pageview and includes UTM params if present in the URL. Call when the route changes (e.g. Next.js router):
tracker.trackPageView();
// optional extra properties
tracker.trackPageView({ section: 'pricing' });Track custom events
tracker.trackEvent('button_clicked', { button: 'signup', page: 'pricing' });Track conversion (demo submit)
Sends Demo_submission with UTM params and optional properties:
tracker.trackConversion({ form_name: 'contact' });Identify users (e.g. after login)
tracker.identify('user-123', { email: '[email protected]', plan: 'pro' });Read UTM params only
const utm = tracker.getUtmParams();
// e.g. { utm_source: 'google', utm_medium: 'cpc' }Next.js example
// app/layout.js (or pages/_app.js)
'use client';
import { tracker } from 'cs_posthog';
import { usePathname } from 'next/navigation';
import { useEffect } from 'react';
export default function RootLayout({ children }) {
const pathname = usePathname();
useEffect(() => {
tracker.init(
process.env.NEXT_PUBLIC_POSTHOG_KEY,
process.env.NEXT_PUBLIC_APP_HOST, // optional; omit for no host check
process.env.NEXT_PUBLIC_POSTHOG_HOST,
false
);
}, []);
useEffect(() => {
if (pathname) tracker.trackPageView();
}, [pathname]);
return <html>{children}</html>;
}Use env vars for the API key and hosts (e.g. NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com).
API
| Method | Description |
|--------|-------------|
| tracker.init(apiKey, customDomain, capturePageView) | Init with no host check. capturePageView defaults to false. |
| tracker.init(apiKey, allowedHost, customDomain, capturePageView) | Init only when window.location.host === allowedHost. |
| tracker.trackPageView(extraProperties?) | Sends $pageview with UTM params from URL and optional extra properties. |
| tracker.trackEvent(eventName, properties?) | Sends a custom event with optional properties. |
| tracker.trackConversion(properties?) | Sends Demo_submission with UTM params and optional properties. |
| tracker.identify(userId, traits?) | Identifies the user with optional person traits. |
| tracker.getUtmParams() | Returns { utm_source?, utm_medium?, ... } from the current URL. |
All methods no-op when window is undefined (SSR).
Build & demo (developers)
From the repo root:
npm install
npm run build # dist/index.js (CommonJS, for Node/bundlers)
npm run build:demo # dist/index.browser.js (IIFE, for script tag)
npm run dev # watch mode for dist/index.js
npm run demo # build browser bundle + start demo server on port 5000Then open http://localhost:5000/demo/ to try the tracker (pageview, events, conversion, identify, UTM display). Use ?utm_source=google&utm_medium=cpc in the URL to test UTM capture.
License
ISC · Author: Aravind CP