next-rybbit
v0.2.2
Published
Simple integration for Rybbit Analytics in Next.js applications
Maintainers
paulharrerReadme
next-rybbit
Next.js integration for Rybbit Analytics - A simple, privacy-focused analytics solution.
Installation
npm install next-rybbit
# or
yarn add next-rybbit
# or
pnpm add next-rybbitUsage
App Router (Recommended)
Wrap your app in the RybbitProvider in your root layout:
// app/layout.tsx
import { RybbitProvider } from 'next-rybbit';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<RybbitProvider siteId="YOUR_SITE_ID">
{children}
</RybbitProvider>
</body>
</html>
);
}Pages Router
Wrap your app in the RybbitProvider in _app.tsx:
// pages/_app.tsx
import { RybbitProvider } from 'next-rybbit';
import type { AppProps } from 'next/app';
export default function App({ Component, pageProps }: AppProps) {
return (
<RybbitProvider siteId="YOUR_SITE_ID">
<Component {...pageProps} />
</RybbitProvider>
);
}Configuration
Props
| Prop | Type | Required | Default | Description |
|----------------------|------|----------|---------|-------------|
| siteId | string | ✅ | - | Your Rybbit site ID |
| analyticsHost | string | ❌ | https://app.rybbit.io/api | Custom analytics host URL |
| children | React.ReactNode | ✅ | - | Your app content |
Custom Analytics Host
If you're using a self-hosted Rybbit instance, you can specify a custom analytics host:
<RybbitProvider
siteId="YOUR_SITE_ID"
analyticsHost="https://your-custom-host.com/api"
>
{children}
</RybbitProvider>How it works
The RybbitProvider component automatically loads the Rybbit analytics script with the correct configuration. It uses Next.js's Script component with the afterInteractive strategy to ensure optimal performance.
The script is loaded from {analyticsHost}/script.js and configured with your site ID.
Tracking API
You can use the useRybbit hook to access tracking functions in your components:
import { useRybbit } from 'next-rybbit';
function MyComponent() {
const { trackEvent, trackPageview, identify, setTraits, clearUserId, getUserId } = useRybbit();
// Use tracking functions here
}trackEvent
Tracks a custom event with a name and optional parameters.
const { trackEvent } = useRybbit();
// Basic usage - just the event name
trackEvent('button_clicked');
// With custom properties
trackEvent('product_purchased', {
props: {
productId: 'prod-123',
price: 49.99,
currency: 'USD'
}
});
// With callback function
trackEvent('form_submitted', {
props: { formId: 'contact' },
callback: () => {
console.log('Event tracked successfully');
}
});trackPageview
Tracks a page view with optional parameters.
const { trackPageview } = useRybbit();
// Basic usage - tracks current page
trackPageview();
// With custom URL and properties
trackPageview({
url: '/custom-path',
referrer: 'https://example.com',
deviceWidth: 1024,
props: {
section: 'blog',
category: 'tech'
}
});identify
Associates the current visitor with a user ID and optional properties.
const { identify } = useRybbit();
// Basic usage - just set user ID
identify('user-123');
// With user properties
identify('user-123', {
plan: 'premium',
subscribed: true,
loginCount: 42
});setTraits
Updates traits for the currently identified user without re-identifying them. Requires identify() to have been called first.
const { setTraits } = useRybbit();
// Update user traits
setTraits({
plan: 'enterprise',
upgraded_at: '2024-01-15'
});
// Remove a trait by setting it to null
setTraits({
temporary_flag: null
});clearUserId
Clears the currently set user ID.
const { clearUserId } = useRybbit();
// Use on logout
const handleLogout = () => {
// Logout logic
clearUserId();
};getUserId
Returns the currently set user ID.
const { getUserId } = useRybbit();
// Check if user is identified
const currentUserId = getUserId();
if (currentUserId) {
console.log('User is identified as:', currentUserId);
} else {
console.log('User is anonymous');
}TypeScript Support
This package includes full TypeScript support with type definitions.
License
MIT