Installation & Setup

CDN Script

Insert snippet inside your site’s <head> … </head> tags:

<script
  defer
  src="https://assets.onedollarstats.com/stonks.js"
  data-debug="mydomain.com"
></script>

Attrubute	Type	Default	Description
`data-url`	`URL`	`https://collector.onedollarstats.com/events`	URL to send analytics events
`data-debug`	`string \| null`	`null`	Replace localhost hostname for dev testing
`data-hash-routing`	`boolean`	`false`	Track hash route changes as pageviews
`data-autocollect`	`boolean`	`true`	Automatically track pageviews & clicks

The analytics script allows you to send events and page views manually.

// Send page view
window.stonks.view("/homepage");

// Send page view with custom properties
window.stonks.view("/checkout", { step: 2, plan: "pro" });

// Send custom event
window.stonks.event("Purchase");

// Send custom event with path
window.stonks.event("Purchase", "/product");

// Send custom event with properties
window.stonks.event("Purchase", { amount: 1, color: "green" });

// Send custom event with path and properties
window.stonks.event("Purchase", "/product", { amount: 1, color: "green" });

You can find a complete guide on how to manually send events and page views in the Send Events and Send Page Views sections.

NPM Package

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

Getting Started

Installation

npm i onedollarstats

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`	Replace localhost hostname for dev testing
`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 trackLocalhostAs option 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.

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