https://github.com/nks-hub/rybbit-ts
Privacy-first analytics SDK for TypeScript — typed GA4-compatible events, GTM bridge, event queuing, zero cookies. Wrapper for Rybbit Analytics with ESM, IIFE and script tag support.
https://github.com/nks-hub/rybbit-ts
analytics cookieless ecommerce event-tracking ga4 gdpr google-tag-manager gtm npm privacy rybbit sdk typescript web-analytics
Last synced: 16 days ago
JSON representation
Privacy-first analytics SDK for TypeScript — typed GA4-compatible events, GTM bridge, event queuing, zero cookies. Wrapper for Rybbit Analytics with ESM, IIFE and script tag support.
- Host: GitHub
- URL: https://github.com/nks-hub/rybbit-ts
- Owner: nks-hub
- Created: 2026-02-06T17:33:44.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-26T22:41:38.000Z (2 months ago)
- Last Synced: 2026-04-27T00:24:04.792Z (2 months ago)
- Topics: analytics, cookieless, ecommerce, event-tracking, ga4, gdpr, google-tag-manager, gtm, npm, privacy, rybbit, sdk, typescript, web-analytics
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@nks-hub/rybbit
- Size: 83 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# @nks-hub/rybbit-ts
[](https://github.com/nks-hub/rybbit-ts/actions)
[](https://www.npmjs.com/package/@nks-hub/rybbit-ts)
[](LICENSE)
> Privacy-first analytics SDK for TypeScript - A modern wrapper for [Rybbit Analytics](https://rybbit.io) with typed events, GTM integration, and zero-configuration setup.
---
## Why Rybbit?
**Privacy-first. Cookieless. No consent popups needed.**
Rybbit Analytics provides GDPR-compliant, cookieless tracking without requiring user consent dialogs. This SDK makes integration effortless with:
- **Zero cookies** - No consent banners required
- **TypeScript-first** - Fully typed GA4-compatible events
- **GTM-ready** - Seamless Google Tag Manager bridge
- **Queue management** - Never lose events during initialization
- **Multiple loading strategies** - Works with any setup
---
## Quick Start
### Installation
```bash
npm install @nks-hub/rybbit-ts
```
### Usage
#### ES Module
```typescript
import nksRybbit from '@nks-hub/rybbit-ts';
// Initialize SDK
await nksRybbit.boot({
host: 'https://demo.rybbit.com',
siteId: 'your-site-id'
});
// Track events
nksRybbit.event('click_cta', { button: 'hero' });
// E-commerce tracking
nksRybbit.trackPurchase({
transactionId: 'TX-001',
value: 1299,
currency: 'CZK'
});
```
#### Script Tag (IIFE)
```html
NksRybbit.default.boot({
host: 'https://demo.rybbit.com',
siteId: 'your-site-id'
});
NksRybbit.default.event('page_view');
```
---
## Features
| Feature | Description |
|---------|-------------|
| **3 Loading Strategies** | Script injection, @rybbit/js SDK integration, or auto-detect |
| **Event Queuing** | Buffers events before SDK ready, replays on initialization |
| **Typed Events** | Full TypeScript support for GA4-compatible events (purchase, add_to_cart, view_item, etc.) |
| **GTM Bridge** | Auto-forward Google Tag Manager dataLayer events to Rybbit |
| **User Identification** | Automatic user ID extraction from server-rendered DOM |
| **Dry-run Mode** | Test integration by logging events without sending |
| **Session Replay** | Programmatic control over session recording |
---
## Bot Detection & E2E Testing
Since Rybbit `v2.5` the analytics script ships an automatic client-side bot
score (`_bs`). The server silently drops events when it considers the request
a bot — including all of these patterns:
- `navigator.webdriver === true` (Selenium / Playwright / Puppeteer default)
- Headless Chrome (SwiftShader WebGL renderer, missing `window.chrome`, no plugins)
- `outerWidth/outerHeight === 0`, `connection.rtt === 0`
- Server-side: viewport `800×600` on a desktop User-Agent (Puppeteer default)
The SDK does not build payloads itself — the server-served `script.js` adds
`_bs` automatically — so existing integrations stop seeing automated traffic
without any code change.
**For your own E2E tests**, set `dryRun: true` so the SDK never loads
`script.js` and instead logs every call locally:
```typescript
await nksRybbit.boot({
host: 'https://demo.rybbit.com',
siteId: 'your-site-id',
dryRun: process.env.NODE_ENV === 'test',
});
```
Without `dryRun`, your Playwright/Puppeteer test runs will be flagged as bots
and silently dropped (the request still returns `200 OK` but with
`message: "bot detected"` — no error surfaces in the browser).
---
## Documentation
Comprehensive guides to get you up and running:
| Guide | Description |
|-------|-------------|
| [Getting Started](docs/getting-started.md) | Installation, configuration, and loading strategies |
| [Events Reference](docs/events.md) | Complete catalog of typed events with examples |
| [GTM Bridge](docs/gtm-bridge.md) | Google Tag Manager integration guide |
| [API Reference](docs/api.md) | Full SDK API documentation |
| [Examples](docs/examples.md) | Real-world integration examples |
---
## Build Outputs
| File | Format | Size | Use Case |
|------|--------|------|----------|
| `dist/index.esm.js` | ESM | ~24 KB | Modern bundlers (Vite, webpack, Rollup) |
| `dist/index.js` | CJS | ~25 KB | Node.js / require() imports |
| `dist/index.iife.js` | IIFE | ~26 KB | Direct script tag (development) |
| `dist/index.iife.min.js` | IIFE | ~13 KB | Direct script tag (production) |
| `dist/index.d.ts` | Types | ~10 KB | TypeScript definitions |
---
## Configuration Example
```typescript
import nksRybbit from '@nks-hub/rybbit-ts';
await nksRybbit.boot({
// Required
host: 'https://demo.rybbit.com',
siteId: 'your-site-id',
// Optional
loadStrategy: 'detect', // 'detect' | 'script' | 'sdk'
debug: false, // Console logging
dryRun: false, // Test mode (log only)
gtmBridge: true, // Forward GTM events
gtmEvents: ['purchase'], // Whitelist GTM events
autoIdentify: true, // Auto-detect user from DOM
globalProperties: { site: 'my-site' }
});
```
---
## Development
```bash
# Install dependencies
npm install
# Build SDK
npm run build
# Type checking
npm run typecheck
# Run tests
npm test
# Watch mode
npm run dev
```
---
## Requirements
- **Node.js**: 16+ recommended
- **TypeScript**: 5.0+ (for TypeScript projects)
- **Browsers**: Modern browsers with ES6 support
---
## Contributing
Contributions are welcome! For major changes, please open an issue first.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: description'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Support
- 📧 **Email:** dev@nks-hub.cz
- 🐛 **Bug reports:** [GitHub Issues](https://github.com/nks-hub/rybbit-ts/issues)
- 🐸 **Rybbit Analytics:** [rybbit.io](https://rybbit.io)
## License
MIT License — see [LICENSE](LICENSE) for details.
---
Made with ❤️ by NKS Hub