OneDollarStats

$1.00/month web analytics 🚀

Website • Documentation • Discord

What's onedollarstats package?

OneDollarStats is a lightweight, zero-dependency analytics library for client applications that automatically tracks pageviews, UTM parameters, and custom events with minimal setup. It supports hash-based navigation, automatically collects UTM parameters, tracks clicks on elements with data-s-event attributes, and integrates effortlessly.

Installation

npm i onedollarstats

Getting Started

Configure analytics

⚠️ Initialize analytics on every page for static sites, or at the root layout (app entrypoint) in SPA apps. Calling view or event before configure will automatically initialize the tracker with the default configuration.

import { configure } from "onedollarstats";

// Configure analytics
configure({
  collectorUrl: "https://collector.onedollarstats.com/events",
  autocollect: true, // automatically tracks pageviews & clicks
  hashRouting: true // track SPA hash route changes
});

Manual Tracking

Note: Any path or properties you pass to view or event take priority over values found on the page (like data-s-path, data-s-view-props, or meta tags).

Track Pageviews

By default, pageviews are tracked automatically. If you want to track them manually (for example, with autocollect: false), you can use the view function:

import { view } from "onedollarstats";

// Simple pageview
view("/homepage");

// Pageview with extra properties
view("/checkout", { step: 2, plan: "pro" });

Track Custom Events

The event function can accept different types of arguments depending on your needs:

import { event } from "onedollarstats";

// Simple event
event("Purchase");

// Event with a path
event("Purchase", "/product");

// Event with properties
event("Purchase", { amount: 1, color: "green" });

// Event with path + properties
event("Purchase", "/product", { amount: 1, color: "green" });

API

configure(config?: AnalyticsConfig) initializes the tracker with your configuration.

Config Options:

Option	Type	Default	Description
collectorUrl	string	https://collector.onedollarstats.com/events	URL to send analytics events
trackLocalhostAs	string | null	null	Deprecated. Use hostname and devmode
hostname	string | null	null	Override event hostname(for server-side or desktop runtimes) Required for devmode
devmode	boolean	false	For dev testing, requires hostname
hashRouting	boolean	false	Track hash route changes as pageviews
autocollect	boolean	true	Automatically track pageviews & clicks
excludePages	string[]	[]	Pages to ignore for automatic tracking
includePages	string[]	[]	Pages to explicitly include for tracking

Notes:

• Manual calls of view or event ignore excludePages/includePages.
• By default, events from localhost are ignored. Use the hostname and devmode options to simulate a hostname for local development.

---

view(pathOrProps?: string | Record<string, string>, props?: Record<string, string>) sends a pageview event.

Parameters:

• pathOrProps – Optional, string represents the path, object represents custom properties.
• props – Optional, properties if the first argument is a path string.

---

event(eventName: string, pathOrProps?: string | Record<string, string>, props?: Record<string, string>) sends a custom event.

Parameters:

• eventName – Name of the event.
• pathOrProps – Optional, string represents the path, object represents custom properties.
• props – Optional, properties if the second argument is a path string.

Expo

onedollarstats/expo is a dedicated entry point for Expo apps using expo-router. It auto-collects pageviews on route change and on app foreground, supports dynamic-route templates (/profile/[id] instead of /profile/abc123), and sends events natively on iOS/Android and via image beacon + sendBeacon on web.

// app/_layout.tsx
import { Stack } from 'expo-router';
import { OneDollarStatsProvider } from 'onedollarstats/expo';

export default function RootLayout() {
  return (
    <OneDollarStatsProvider config={{ hostname: 'example.com' }}>
      <Stack screenOptions={{ headerShown: false }} />
    </OneDollarStatsProvider>
  );
}

Fire custom events or manual pageviews from any component with useAnalytics():

import { useAnalytics } from 'onedollarstats/expo';

const { event, view } = useAnalytics();

event('signup', { plan: 'pro' });        // event with current route
event('signup', '/landing');              // event with explicit path
view({ campaign: 'spring' });             // pageview with just props
view('/landing', { campaign: 'spring' }); // pageview with explicit path

Expo-specific config options:

Option	Type	Default	Description
collapseDynamicRoutes	boolean	true	Use useSegments() to record routes as templates (/profile/[id]) instead of concrete paths. Group segments like (tabs) are stripped.

All other options (hostname, collectorUrl, devmode, autocollect, excludePages, includePages) behave the same as in the web tracker above.

Autocapture

Page view events

List of attributes for tags that allow modifying the sent page view:

• data-s-path – Optional. Specifies the path representing the page where the event occurred. This attribute should be set on the <body> tag.

• data-s-view-props – Optional. Defines additional properties to include with the page view event. All properties from elements on the page with this attribute will be collected and sent together.

Click events

Automatically capture clicks on elements using these HTML attributes:

• data-s-event– Name of the event
• data-s-event-path Optional, the path representing the page where the event occurred
• data-s-event-props – Optional, properties to send with the event

See full onedollarstats documentation.