@cookieless-tech/react
v0.0.0
Published
Framework-agnostic React package for integrating Cookieless Analytics
Downloads
92
Maintainers
eamongordonReadme
@cookieless-tech/react
A framework-agnostic React package for integrating Cookieless Analytics into any React application (Vite, Remix, Create React App, etc.).
This package acts as a lightweight wrapper around the core cookieless tracking script, automatically injecting it into your app and providing type-safe React hooks for custom interactions.
Installation
To install the package from npm:
npm install @cookieless-tech/reactSetup
Wrap your application (or the part of your application you want to track) with the <Analytics> provider. This component will dynamically inject the tracking script into the DOM.
import { Analytics } from '@cookieless-tech/react';
function App() {
return (
<Analytics
siteId="YOUR_SITE_ID"
// Optional configurations:
// debug={true}
// blockSelectors=".sensitive-data, #payment-form"
// customProperties={{ plan: 'pro' }}
>
<YourAppComponents />
</Analytics>
);
}Configuration Options
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| siteId | string | Required | Your Cookieless Analytics Site ID |
| scriptSrc | string | https://cdn.cookieless.tech/script.js | Override the tracking script URL |
| debug | boolean | false | Enable console debug logging |
| blockSelectors | string | undefined | CSS selectors for elements to block from session replay |
| customProperties | Record<string, string> | undefined | Custom properties to attach globally via script attributes |
Usage
1. Tracking Page Views
For Single Page Applications (SPAs) where the URL changes without a full page load, you can trigger page views manually using the usePageView hook.
import { usePageView } from '@cookieless-tech/react';
function DashboardRoute() {
// Triggers a pageview automatically when this component mounts!
usePageView({ section: 'dashboard' });
return <div>Dashboard content...</div>;
}2. Tracking Custom Events
Use the useTrackEvent hook to send custom events when users interact with your app.
import { useTrackEvent } from '@cookieless-tech/react';
function SignupButton() {
const trackEvent = useTrackEvent();
const handleSignup = () => {
// Sends a 'signup_completed' event
trackEvent('signup_completed', {
plan: 'enterprise',
revenue: 299 // If revenue is attached, it will be aggregated
});
};
return <button onClick={handleSignup}>Sign Up</button>;
}3. Setting Global Properties
If you want to attach metadata (like user role or subscription tier) to all future events the user generates during their session, use the useCustomProperties hook.
import { useCustomProperties } from '@cookieless-tech/react';
import { useEffect } from 'react';
function UserProfile({ user }) {
const setProperties = useCustomProperties();
useEffect(() => {
if (user) {
setProperties({
role: user.role,
workspaceId: user.workspaceId
});
}
}, [user, setProperties]);
return <div>User Profile</div>;
}Under the Hood
Unlike @repo/next which has server-side logic and Next.js router integrations, this package does not assume any specific routing framework.
When you use the <Analytics> provider, it dynamically injects the following into your <head>:
<script
src="https://cdn.cookieless.tech/script.js"
defer=""
data-site-id="YOUR_SITE_ID"
></script>The React hooks (useTrackEvent, usePageView, useCustomProperties) simply pass data down to the globally exposed window.cookieless interface created by that script.