React SDK
React hooks and components for Entrolytics
React SDK
The @entro314labs/entro-react package provides React hooks and components for tracking analytics in any React application.
Installation
pnpm add @entro314labs/entro-reactnpm install @entro314labs/entro-reactyarn add @entro314labs/entro-reactbun add @entro314labs/entro-reactQuick Start
Add Provider
Wrap your app with EntrolyticsProvider:
import { EntrolyticsProvider } from '@entro314labs/entro-react'
function App() {
return (
<EntrolyticsProvider
websiteId={import.meta.env.VITE_ENTROLYTICS_WEBSITE_ID}
host={import.meta.env.VITE_ENTROLYTICS_HOST}
autoTrack={true}
>
<YourApp />
</EntrolyticsProvider>
)
}Add Environment Variables
Create a .env file:
VITE_ENTROLYTICS_WEBSITE_ID=your-website-id
VITE_ENTROLYTICS_HOST=https://cloud.entrolytics.clickTrack Events
Use the useEntrolytics hook:
import { useEntrolytics } from '@entro314labs/entro-react'
function SignupButton() {
const { track } = useEntrolytics()
return (
<button onClick={() => track('signup', { plan: 'pro' })}>
Sign Up
</button>
)
}Configuration
interface EntrolyticsConfig {
websiteId?: string;
linkId?: string;
pixelId?: string;
host?: string;
autoTrack?: boolean;
useEdgeRuntime?: boolean; // Use edge-optimized endpoints (default: true)
tag?: string;
domains?: string[];
excludeSearch?: boolean;
excludeHash?: boolean;
respectDoNotTrack?: boolean;
ignoreLocalhost?: boolean;
beforeSend?: BeforeSendCallback;
trackOutboundLinks?: boolean;
proxy?: ProxyConfig | false;
debug?: boolean;
}Runtime Configuration
The useEdgeRuntime prop controls which collection endpoint is used:
Edge Runtime (default) - Optimized for speed and global distribution:
<EntrolyticsProvider
websiteId="your-website-id"
useEdgeRuntime={true} // or omit (default)
>
<App />
</EntrolyticsProvider>- Latency: Sub-50ms response times globally
- Best for: Production apps, globally distributed users
- Endpoint: Uses
/api/send-nativefor edge-to-edge communication - Limitations: No ClickHouse export, basic geo data
Node.js Runtime - Full-featured with advanced capabilities:
<EntrolyticsProvider
websiteId="your-website-id"
useEdgeRuntime={false}
>
<App />
</EntrolyticsProvider>- Features: ClickHouse export, MaxMind GeoIP (city-level accuracy)
- Best for: Self-hosted deployments, advanced analytics requirements
- Endpoint: Uses
/api/sendfor Node.js runtime - Latency: 50-150ms (regional)
When to use Node.js runtime:
- Self-hosted deployments without edge runtime support
- Applications requiring ClickHouse data export
- Need for advanced geo-targeting with MaxMind
- Custom server-side analytics workflows
See the Intelligent Routing guide for more details on collection endpoints.
Hooks
useEntrolytics
const {
track,
trackView,
identify,
trackRevenue,
trackOutboundLink,
setTag,
isReady,
isEnabled,
} = useEntrolytics();usePageView
import { usePageView } from '@entro314labs/entro-react';
function Page() {
usePageView(); // Auto-track on mount and route changes
}Components
TrackEvent
import { TrackEvent } from '@entro314labs/entro-react';
<TrackEvent name="cta-click" data={{ location: 'hero' }}>
<button>Click Me</button>
</TrackEvent>OutboundLink
import { OutboundLink } from '@entro314labs/entro-react';
<OutboundLink href="https://example.com">
External Link
</OutboundLink>Framework Examples
Vite + React
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { EntrolyticsProvider } from '@entro314labs/entro-react';
import App from './App';
createRoot(document.getElementById('root')!).render(
<StrictMode>
<EntrolyticsProvider
websiteId={import.meta.env.VITE_ENTROLYTICS_WEBSITE_ID}
>
<App />
</EntrolyticsProvider>
</StrictMode>
);React Router
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
import { useEntrolytics } from '@entro314labs/entro-react';
function RouteTracker() {
const location = useLocation();
const { trackView } = useEntrolytics();
useEffect(() => {
trackView(location.pathname + location.search);
}, [location, trackView]);
return null;
}
// Add to your app
<RouteTracker />