Tracking Events

Track user actions and product usage with the useAnalytics hook.

Basic Usage

"use client"

import {  } from "@repo/analytics"

export function ({  }: { : string }) {
  const {  } = ()

  const  = () => {
    ("PLAN_SELECTED", {
      ,
      : "pricing_page"
    })
  }

  return (
    < ={}>
      Select {}
    </>
  )
}

The track() Function

track(event: string, properties?: Record<string, unknown>)

Parameter	Type	Description
`event`	`string`	Event name (e.g., `"BUTTON_CLICKED"`)
`properties`	`object`	Optional metadata about the event

Event Naming Conventions

Use ALL_CAPS_SNAKE_CASE for event names:

// Good
("USER_SIGNED_UP")
("PLAN_UPGRADED")
("FEATURE_USED")

// Avoid
("user signed up")
("planUpgraded")
("feature-used")

This convention:

Makes events easy to find in analytics dashboards
Clearly distinguishes events from other data
Is widely adopted across analytics tools

Common Event Patterns

("BUTTON_CLICKED", { : "cta", : "home" })
("FORM_SUBMITTED", { : "contact", : true })
("LINK_CLICKED", { : "/pricing", : false })

Feature Usage

("FEATURE_USED", { : "dark_mode", : true })
("SEARCH_PERFORMED", { : "billing", : 5 })
("FILTER_APPLIED", { : "date", : "last_7_days" })

Business Events

("PLAN_SELECTED", { : "pro", : "monthly" })
("CHECKOUT_STARTED", { : "pro", : 29 })
("SUBSCRIPTION_CREATED", { : "pro", : false })

Errors

("ERROR_OCCURRED", { 
  : "PAYMENT_FAILED",
  : "Card declined"
})

Adding Properties

Include relevant context with every event:

("DOCUMENT_CREATED", {
  : .,
  : "invoice",
  : .,
  : true
})

Properties help you:

Filter and segment in analytics dashboards
Debug issues with more context
Build funnels and cohorts

Tracking on Page Load

For events that should fire when a page loads:

"use client"

import {  } from "@repo/analytics"
import {  } from "react"

export function () {
  const {  } = ()

  (() => {
    ("PRICING_PAGE_VIEWED", {
      : .
    })
  }, [])

  return <>Pricing content...</>
}

Automatic Page Tracking

The AnalyticsProvider automatically tracks page views when routes change. You don't need to manually call track() for page views.

The automatic tracking:

Fires on every route change
Filters out route groups (e.g., (dashboard))
Replaces long IDs with :id for cleaner data

Example transformations:

/dashboard/(settings)/profile/abc123 → /dashboard/profile/:id
/(marketing)/pricing → /pricing

Disable Auto Page Tracking

< 
  ={} 
  ={}
  ={false}
>
  {}
</>

Type-Safe Events

For better type safety, define your events:

types/analytics.ts

interface AnalyticsEvents {
  : { : string }
  : { : string; : "monthly" | "yearly" }
  : { : string; : boolean }
}

type  = keyof AnalyticsEvents

Then create a typed wrapper:

lib/analytics.ts

import { useAnalytics as  } from "@repo/analytics"

export function () {
  const  = ()

  return {
    ...,
    : < extends >(
      : ,
      : AnalyticsEvents[]
    ) => .track(, )
  }
}

Best Practices

Be consistent - Use the same event name for the same action across your app
Include context - Add properties that help you understand the event
Don't over-track - Focus on events that drive business decisions
Avoid PII - Don't include emails, names, or other personal data in properties
Use present tense verbs - BUTTON_CLICKED not BUTTON_WAS_CLICKED

Next Steps

Identify users - Associate events with users
Feature flags - Control feature rollouts