npm.io
0.1.1 • Published 2d ago

ribby-sdk

Licence
MIT
Version
0.1.1
Deps
0
Size
170 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

ribby

Lightweight analytics and Web Vitals tracking for React, Next.js, Vite, and any JavaScript app.

Installation

npm install ribby-sdk
# or
yarn add ribby
# or
pnpm add ribby

React / Vite

// src/main.tsx or src/App.tsx
import { RibbyAnalytics } from 'ribby-sdk/react'

function App() {
  return (
    <>
      <RibbyAnalytics siteKey="YOUR_SITE_KEY" />
      {/* rest of your app */}
    </>
  )
}

Next.js (App Router)

// app/layout.tsx
import { RibbyAnalytics } from 'ribby-sdk/next'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <RibbyAnalytics siteKey="YOUR_SITE_KEY" />
        {children}
      </body>
    </html>
  )
}

Next.js (Pages Router)

// pages/_app.tsx
import { RibbyAnalytics } from 'ribby-sdk/next'
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <RibbyAnalytics siteKey="YOUR_SITE_KEY" />
      <Component {...pageProps} />
    </>
  )
}

Vanilla JS / HTML (no bundler)

<script>
  window.ribby = { q: [] };
  window.ribby.init = (c) => window.ribby.q.push(['init', c]);
  window.ribby.track = (e, p) => window.ribby.q.push(['track', e, p]);
</script>
<script defer src="https://cdn.ribby.app/analytics.js" data-site-key="YOUR_SITE_KEY"></script>

Tracking custom events

import { track } from 'ribby-sdk/react'
// or from 'ribby-sdk/next'
// or from 'ribby'

// Track a button click
track('signup_click', { plan: 'pro' })

// Track a purchase
track('purchase', { value: 49.99, currency: 'USD' })

Or use the hook:

import { useRibby } from 'ribby-sdk/react'

function SignUpButton() {
  const { track } = useRibby()

  return (
    <button onClick={() => track('signup_click', { plan: 'pro' })}>
      Sign up
    </button>
  )
}

Configuration

<RibbyAnalytics
  siteKey="YOUR_SITE_KEY"  // required — from your Ribby dashboard
  vitals={true}             // collect Web Vitals (LCP, FID, CLS, TTFB, FCP). default: true
  disabled={false}          // disable tracking entirely. default: false
  trackHashChanges={true}   // track hash-based SPA navigation. default: true
/>

What gets tracked

Data Description
Page URL Current page path (no query strings with sensitive data)
Referrer Where the visitor came from
Device type Desktop / Mobile / Tablet
Browser Chrome / Safari / Firefox / Edge
Session ID Random ID per browser session (not stored server-side between sessions)
Web Vitals LCP, FID, CLS, TTFB, FCP — only if vitals={true}

No cookies are set. Sessions use sessionStorage which clears when the tab closes.
Do Not Track is respected. If the visitor has DNT enabled, no data is sent.

Privacy

  • No cookies
  • No cross-site tracking
  • Respects Do Not Track
  • No personal data collected (no IPs stored, no fingerprinting)
  • GDPR-friendly by design

Your site key

Find your site key in the Ribby dashboard → Analytics → Setup.

Keywords

analyticsweb-vitalsreactnextjsribbytrackingqa