https://github.com/0xdeafcafe/react-contextual-analytics
React Contextual Analytics is an context-driven approach to blah blah
https://github.com/0xdeafcafe/react-contextual-analytics
analytics analytics-framework analytics-tracking developer-exp react react-context
Last synced: 11 days ago
JSON representation
React Contextual Analytics is an context-driven approach to blah blah
- Host: GitHub
- URL: https://github.com/0xdeafcafe/react-contextual-analytics
- Owner: 0xdeafcafe
- Created: 2025-05-20T07:50:11.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-10-15T19:29:18.000Z (6 months ago)
- Last Synced: 2025-10-22T05:35:45.540Z (6 months ago)
- Topics: analytics, analytics-framework, analytics-tracking, developer-exp, react, react-context
- Language: TypeScript
- Homepage:
- Size: 274 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# react-contextual-analytics
[](https://badge.fury.io/js/react-contextual-analytics)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://reactjs.org/)
[](https://bundlephobia.com/package/react-contextual-analytics)
[](https://github.com/0xdeafcafe/react-contextual-analytics/actions)
[](https://codecov.io/gh/0xdeafcafe/react-contextual-analytics)
A React framework for collecting and emitting analytics events with minimal boilerplate. Automatically collects context through component boundaries, making analytics implementation simpler and more maintainable.
## Quick Start
```bash
# Install
npm install react-contextual-analytics
# or
yarn add react-contextual-analytics
# or
pnpm add react-contextual-analytics
```
```jsx
// 1. Create your analytics client
import {
createAnalyticsClient,
AnalyticsProvider,
AnalyticsBoundary
} from 'react-contextual-analytics';
import { console, google } from 'react-contextual-analytics/providers';
const analyticsClient = createAnalyticsClient([
console, // For development logging
google, // For Google Analytics
]);
// 2. Wrap your app
function App() {
return (
);
}
// 3. Start collecting analytics
function ProductPage({ product }) {
return (
{(emitter) => (
emit('clicked', 'add-to-cart')}>
Add to Cart
)}
);
}
```
## Key Concepts
### 1. Context Collection
- Wrap components with `AnalyticsBoundary` to define context
- Context is automatically inherited from parent boundaries
- Events include all relevant context from their location in the tree
```jsx
import { AnalyticsBoundary } from 'react-contextual-analytics';
function StorePage() {
return (
{(emitter) => (
emit('clicked', 'view-details')}>
View Product
)}
);
}
// Event includes: {
// boundary: "store.product",
// context: { storeId: "123", productId: "456" }
// }
```
### 2. Event Emission
Two ways to emit events:
1. **Using Boundary Callback** (recommended for multiple events):
```jsx
import { AnalyticsBoundary } from 'react-contextual-analytics';
function CheckoutForm() {
return (
{(emitter) => (
emit('clicked', 'purchase', {
amount: 99.99,
productId: '123'
})}>
Buy Now
emit('clicked', 'cancel')}>
Cancel
)}
);
}
```
2. **Using Hook** (for single events):
```jsx
import { useAnalytics } from 'react-contextual-analytics';
function AddToCartButton({ productId }) {
const { emit } = useAnalytics();
return (
emit('clicked', 'add-to-cart', { productId })}
>
Add to Cart
);
}
```
### 3. Event Structure
```typescript
interface Event {
action: string; // e.g., 'clicked', 'viewed'
name?: string; // e.g., 'add-to-cart', 'purchase'
boundary?: string; // e.g., 'store.product'
attributes?: object; // Event-specific data
context?: { // Automatically collected
href: string;
windowWidth: number;
// ... other global context
};
}
```
## Best Practices
1. **Boundary Organization**
- Place boundaries around logical sections (pages, features, forms)
- Keep hierarchy shallow (2-3 levels)
- Use meaningful names
2. **Context Management**
- Define context at highest relevant level
- Use consistent attribute names
- Avoid context duplication
3. **Event Naming**
- Use consistent actions: 'clicked', 'viewed', 'submitted'
- Make names descriptive but concise
- Follow consistent patterns
## Custom Providers
Create custom providers by implementing the Provider interface:
```typescript
interface Provider {
id: string;
send: (event: Event) => Promise;
setup?: () => void;
}
// Example: Sentry Provider
const sentryProvider = {
id: 'sentry',
send: (event) => {
captureBreadcrumb({
message: [event.boundary, event.name, event.action].filter(Boolean).join(' '),
level: 'info',
});
}
};
```
## API Reference
- `AnalyticsProvider`: Root provider component
- `AnalyticsBoundary`: Context boundary component
- `useAnalytics`: Hook for emitting events
- `createAnalyticsClient`: Create analytics client with providers