@bbcd0/analytics
v1.4.0
Published
This package shared analytics utils to be used in all projects across bbcd0.
Readme
@bbcd0/analytics
Shared analytics utilities for bbcd0 projects. Built on top of RudderStack Analytics.
Installation
npm install @bbcd0/analyticsRequirements
- React >= 19.2.0
- React DOM >= 19.2.0
- Next.js >= 16.0.0 when using
@bbcd0/analytics/next - React Router >= 7.0.0 when using
@bbcd0/analytics/react-router - Vite >= 5.0.0 when using
@bbcd0/analytics/vite
Usage
1. Next.js Connection Script
If you are using Next.js, add AnalyticsScript from @bbcd0/analytics/next to your app's root layout:
import { AnalyticsScript } from "@bbcd0/analytics/next";
import type { ReactNode } from "react";
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<head>
<AnalyticsScript />
</head>
<body>{children}</body>
</html>
);
}2. Vite Connection Script
If you are using Vite, add the analytics plugin to your Vite config. It injects the connection script into index.html automatically:
import { analytics } from "@bbcd0/analytics/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [analytics()],
});The plugin accepts optional id and identifier options. By default it uses id="bufferEvents" and the global analytics identifier "analytics".
3. React Router Analytics
If you are using React Router, use the route-aware components from @bbcd0/analytics/react-router.
Render them inside the router context so page views and performance events follow client-side navigation:
// main.ts
import { reportWebVitals } from "@bbcd0/analytics/react";
reportWebVitals({ ignoredSearchParams: ["modal"] });import { AnalyticsContext } from "@bbcd0/analytics/react";
import { PageViewAnalytics, PerformanceAnalytics } from "@bbcd0/analytics/react-router";
import { Outlet } from "react-router";
export function RootRoute() {
return (
<AnalyticsContext
value={{
writeKey: "YOUR_WRITE_KEY",
dataPlaneUrl: "YOUR_DATA_PLANE_URL",
source: {
id: "YOUR_SOURCE_ID",
name: "YOUR_SOURCE_NAME",
workspaceId: "YOUR_WORKSPACE_ID",
},
}}
>
<PageViewAnalytics ignoredSearchParams={["modal"]} />
<PerformanceAnalytics ignoredSearchParams={["modal"]} />
<Outlet />
</AnalyticsContext>
);
}The lower-level @bbcd0/analytics/react entrypoint is still available when you want to pass url manually.
4. Wrap your app with AnalyticsContext
Provide your RudderStack credentials:
import { AnalyticsContext } from "@bbcd0/analytics";
export default function App() {
return (
<AnalyticsContext
value={{
writeKey: "YOUR_WRITE_KEY",
dataPlaneUrl: "YOUR_DATA_PLANE_URL",
source: {
id: "YOUR_SOURCE_ID",
name: "YOUR_SOURCE_NAME",
workspaceId: "YOUR_WORKSPACE_ID",
},
}}
>
<YourApp />
</AnalyticsContext>
);
}5. Use the useAnalytics hook
import { useAnalytics } from "@bbcd0/analytics";
function MyComponent() {
const analytics = useAnalytics();
const handleClick = () => {
analytics?.track("Button Clicked", {
buttonId: "my-button",
});
};
return <button onClick={handleClick}>Click me</button>;
}Configuration
| Prop | Type | Required | Description |
| -------------------------- | --------- | -------- | ----------------------------------------------------------------------------------------- |
| value | object | Yes | Object containing all configuration options |
| value.writeKey | string | Yes | Your RudderStack write key |
| value.dataPlaneUrl | string | Yes | Your RudderStack data plane URL |
| value.source | object | Yes | Source configuration object |
| value.source.id | string | Yes | RudderStack source ID |
| value.source.name | string | Yes | RudderStack source name |
| value.source.workspaceId | string | Yes | RudderStack workspace ID |
| value.enabled | boolean | No | Explicitly enable/disable analytics. Defaults to true in production, false otherwise. |
Development vs Production
Analytics are automatically disabled in non-production environments. To override this:
<AnalyticsContext
value={{
writeKey: "YOUR_WRITE_KEY",
dataPlaneUrl: "YOUR_DATA_PLANE_URL",
source: {
id: "YOUR_SOURCE_ID",
name: "YOUR_SOURCE_NAME",
workspaceId: "YOUR_WORKSPACE_ID",
},
enabled: true, // Force enable in development
}}
>
<YourApp />
</AnalyticsContext>