rybbit-ts

rybbit-ts is a cookieless analytics SDK for Rybbit, written in TypeScript. Anyone deploying Rybbit analytics on more than one website runs into the same things every time. The script loads asynchronously, so clicks in the first seconds are lost. An online store wants to track purchases and the cart, but every developer names the event differently. Marketing has its events set up in Google Tag Manager and does not want to create them a second time. As a thin layer over the Rybbit tracking script, it solves these three things once and the same way for all sites.

What it adds to the Rybbit script itself

Rybbit ships the script.js script, which every instance serves, and the @rybbit/js package for bundled applications. rybbit-ts replaces neither of them and sends no data of its own: it uses one of them and adds a queue, typed events and a Tag Manager bridge on top. Whatever Rybbit adds to the script on the server side, such as the bot detection score in version 2.5, works without a code change.

Benefits in practice

Nothing is lost before the script loads

Calls made before initialisation finishes go into a queue and are replayed in the same order once it starts. A site can call event() right at startup and does not have to wait for the analytics to load. The queue holds up to 100 calls and drops the oldest when it overflows. If the injected script does not start within five seconds, initialisation ends with an error instead of waiting silently; loadTimeout changes the limit.

Three loading strategies, one API

The script strategy injects the Rybbit script into the page, sdk uses the @rybbit/js package, and the default detect recognises what the page already has. The same code works on a traditional website with server templates and in an application built with Vite or webpack, and event calls stay the same when you move from one to the other.

Events with consistent names

Typed methods cover online stores (trackViewItem, trackAddToCart, trackPurchase, trackRefund), accounts, forms, search, file downloads, scroll depth and ratings. Names and properties match GA4 events, so anyone moving from Google Analytics does not have to rename anything. TypeScript checks the required parameters while you write the code.

Tag Manager events without creating them again

The Google Tag Manager bridge picks up the events already in the dataLayer and catches every further push. The gtmEvents list sets which of them get through to Rybbit. Sites that track through GTM get their data into Rybbit without changing any tags.

Click tracking right in the HTML

With the autoTrack option on, an element with the data-nhr-event attribute is recorded on click by itself, and further data-nhr-* attributes become event properties; data-nhr-button-type is sent as button_type. A template developer can add tracking without a single line of JavaScript. In the same way, the SDK reads the logged-in user's ID that the server writes into the page: by default from the element with the data-nhr-user-id attribute; the identitySelector option selects another element.

Tests that do not pollute the statistics

In dryRun mode the Rybbit script is not loaded at all and every call is only written to the console. There is a second reason for it: since version 2.5, Rybbit silently drops traffic from Playwright, Puppeteer and other automated browsers. The server still responds with 200 and the message "bot detected", and no error shows up in the browser, so without dryRun E2E tests would search in vain for why their events never arrived.

How to use it

import nksRybbit from '@nks-hub/rybbit-ts';

await nksRybbit.boot({
  host: 'https://demo.rybbit.com',
  siteId: 'your-site-id',
  loadStrategy: 'detect',
  gtmBridge: true,
  gtmEvents: ['purchase'],
  dryRun: process.env.NODE_ENV === 'test',
});

nksRybbit.trackPurchase({ transactionId: 'TX-001', value: 1299, currency: 'CZK' });

Without a build tool, the IIFE build is loaded with a <script> tag and the SDK is then available as NksRybbit.default. The package has no runtime dependencies. It ships in four forms: ESM for bundlers (about 24 kB), CommonJS (25 kB), IIFE for development (26 kB) and minified IIFE for production (13 kB), plus type definitions. It also supports global properties added to all events, session replay started and stopped from code, outbound links, errors and a callback for every event sent. It sets no cookies itself.

Where it helps

• An agency or company with several sites on Rybbit that wants the same event names everywhere and one place to change them.
• An online store moving from Google Analytics that wants to keep its GA4 events and its Tag Manager setup.
• A website with server-side templates, where the template developer adds click tracking with HTML attributes instead of writing scripts.
• A project with an E2E test suite that must neither skew the statistics nor end up in a silent bot filter.

For Flutter apps there is a companion library, rybbit-flutter-sdk, with the same GA4-style events, so the website and the mobile app send data of the same shape to Rybbit.

Project status

npm has version 0.1.0 from 24 February 2026. The repository is one step ahead with version 0.1.1 from 26 April 2026, which fixes trackPurchase serialisation and documents bot detection in Rybbit 2.5; it has not been published on npm yet. Vitest tests cover the queue, automatic click tracking and the main API. The package used to be published as @nks-hub/rybbit, which is marked as deprecated on npm with a pointer to the new name.

Getting started

npm install @nks-hub/rybbit-ts

Installation instructions and loading strategies, the event catalogue, the Tag Manager bridge description and the API reference are in the docs/ directory of the repository. You need a browser with ES6 and, for TypeScript projects, TypeScript 5.0 or later.

Source code

The code is on GitHub in the nks-hub/rybbit-ts repository under the MIT licence. The package is on npm as @nks-hub/rybbit-ts, latest version 0.1.0.