@zetalyx/react

React bindings for Zetalyx — Provider, hooks, error boundary, and HOC for React applications.

Installation

npm install @zetalyx/react @zetalyx/browser

Quick Start

1. Wrap your app with the provider

import { ZetalyxProvider } from '@zetalyx/react';

function App() {
  return (
    <ZetalyxProvider apiKey="pk_live_your_api_key" userId="user_123">
      <YourApp />
    </ZetalyxProvider>
  );
}

2. Use hooks in any component

import { useTrack, useTrackError, useTrackBehavior, useIdentify } from '@zetalyx/react';

function Dashboard() {
  const track = useTrack();
  const trackError = useTrackError();
  const trackBehavior = useTrackBehavior();
  const identify = useIdentify();

  useEffect(() => {
    track('dashboard_viewed');
  }, []);

  const handleClick = () => {
    trackBehavior('export_clicked', { format: 'csv' });
  };

  return <button onClick={handleClick}>Export</button>;
}

Provider

<ZetalyxProvider
  apiKey="pk_live_..."        // Required
  userId="user_123"           // Optional — auto-calls identify()
  endpoint="https://..."      // Default: 'https://api.zetalyx.com'
  batchSize={10}              // Flush after N events
  flushInterval={5000}        // Flush every N ms
  debug={false}               // Console debug logging
  autoCapture={true}          // Auto-capture window errors
  captureClicks={false}       // Auto-track interactive element clicks
>
  {children}
</ZetalyxProvider>

The provider creates a BrowserClient instance and manages its lifecycle. It automatically shuts down the client on unmount.

Hooks

useZetalyx()

Access the underlying BrowserClient instance directly.

const client = useZetalyx();
await client.flush();

useTrack()

Returns a stable callback for tracking custom events.

const track = useTrack();
track('feature_used', { feature: 'dark_mode' });

useTrackError()

Returns a stable callback for tracking errors.

const trackError = useTrackError();

try {
  await fetchData();
} catch (err) {
  trackError(err, { context: 'data_fetch' });
}

useTrackBehavior()

Returns a stable callback for tracking user behaviors.

const trackBehavior = useTrackBehavior();
trackBehavior('form_submitted', { form: 'contact' });

useIdentify()

Returns a stable callback for identifying users.

const identify = useIdentify();

// After login
identify(user.id, { email: user.email, plan: user.plan });

Error Boundary

Automatically catches React render errors and reports them to Zetalyx.

import { ZetalyxErrorBoundary } from '@zetalyx/react';

// With a static fallback
<ZetalyxErrorBoundary fallback={<div>Something went wrong</div>}>
  <RiskyComponent />
</ZetalyxErrorBoundary>

// With a render function (includes error and reset)
<ZetalyxErrorBoundary
  fallback={(error, reset) => (
    <div>
      <p>Error: {error.message}</p>
      <button onClick={reset}>Try Again</button>
    </div>
  )}
  metadata={{ section: 'dashboard' }}
  onError={(error, errorInfo) => console.error(error)}
>
  <RiskyComponent />
</ZetalyxErrorBoundary>

The error boundary automatically includes the React component stack in the error report.

Higher-Order Component

For class components or when you prefer the HOC pattern:

import { withZetalyx, type WithZetalyxProps } from '@zetalyx/react';

interface Props extends WithZetalyxProps {
  title: string;
}

function MyComponent({ title, zetalyx }: Props) {
  const handleClick = () => {
    zetalyx.track('clicked', { title });
  };

  return <button onClick={handleClick}>{title}</button>;
}

export default withZetalyx(MyComponent);

Full Example

import {
  ZetalyxProvider,
  ZetalyxErrorBoundary,
  useTrack,
  useTrackBehavior,
  useIdentify,
} from '@zetalyx/react';

function App() {
  const [user, setUser] = useState(null);

  return (
    <ZetalyxProvider
      apiKey="pk_live_your_api_key"
      userId={user?.id}
      captureClicks
    >
      <ZetalyxErrorBoundary
        fallback={(error, reset) => (
          <div>
            <h2>Something went wrong</h2>
            <button onClick={reset}>Retry</button>
          </div>
        )}
      >
        <Dashboard />
      </ZetalyxErrorBoundary>
    </ZetalyxProvider>
  );
}

License

MIT