Installation

Install trakoo, then the provider packages and SDKs your app uses.

Install the core package first, then add only the providers your app uses. Core trakoo has no provider SDK dependencies. Providers that wrap a vendor SDK ship as separate @trakoo/* packages, installed next to that SDK.

Core package

pnpm add trakoo

npm install trakoo

yarn add trakoo

bun add trakoo

trakoo’s public API is split by environment:

import { defineEvents, noProperties, typed } from 'trakoo';
import { createClientAnalytics } from 'trakoo/client';
import { createServerAnalytics } from 'trakoo/server';

// Providers without a vendor SDK ship with core
import { PirschClientProvider } from 'trakoo/providers/client';
import { PirschServerProvider } from 'trakoo/providers/server';

// SDK-backed providers ship as separate packages
import { PostHogClientProvider } from '@trakoo/posthog/client';
import { PostHogServerProvider } from '@trakoo/posthog/server';

The root trakoo entry point contains environment-neutral event helpers and shared types. Factories live on trakoo/client and trakoo/server. Use trakoo/providers/client in browser bundles and trakoo/providers/server in server-only code; there is no combined provider entry point. Provider packages follow the same split: import from their /client or /server subpath.

Provider packages

Bento’s browser provider, Pirsch, Visitors, and the Proxy need no SDK and ship with trakoo. PostHog, OpenPanel, Bento’s server provider, and EmitKit each have their own package. Install that package with only the SDK for the side you use.

Provider	Client support	Server support	Package	SDK
PostHog	Yes	Yes	`@trakoo/posthog`	`posthog-js` (client), `posthog-node` (server)
OpenPanel	Yes	Yes	`@trakoo/openpanel`	`@openpanel/web` (client), `@openpanel/sdk` (server)
Bento	Yes, CDN script	Yes	Client: included in `trakoo`; server: `@trakoo/bento`	`@bentonow/bento-node-sdk` (server)
Pirsch	Yes, CDN script	Yes	Included in `trakoo`	None
EmitKit	No	Yes	`@trakoo/emitkit`	`@emitkit/js` 3
Visitors	Yes, CDN script	No	Included in `trakoo`	None
Proxy	Yes	Server ingest helpers	Included in `trakoo`	None

# Client
pnpm add trakoo @trakoo/posthog posthog-js

# Server
pnpm add trakoo @trakoo/posthog posthog-node

Install both SDKs only when you use PostHog on both sides.

# Client
pnpm add trakoo @trakoo/openpanel @openpanel/web

# Server
pnpm add trakoo @trakoo/openpanel @openpanel/sdk

Install both SDKs only when you use OpenPanel on both sides.

# Server
pnpm add trakoo @trakoo/bento @bentonow/bento-node-sdk

BentoClientProvider ships with trakoo and loads Bento from its CDN. Install @trakoo/bento and the SDK only when using BentoServerProvider.

# No extra package required

trakoo’s Pirsch providers call Pirsch directly or load the browser script at runtime.

pnpm add trakoo @trakoo/emitkit @emitkit/js

EmitKit is server-side only. Use the Proxy Provider if you need browser events to reach EmitKit.

# No extra package required

VisitorsClientProvider loads https://cdn.visitors.now/v.js at runtime.

Environment variables

Keep browser tokens public and server keys private.

VITE_POSTHOG_KEY=your-posthog-project-key
VITE_POSTHOG_HOST=https://us.i.posthog.com
VITE_OPENPANEL_CLIENT_ID=your-openpanel-client-id
VITE_BENTO_SITE_UUID=your-bento-site-uuid
VITE_VISITORS_TOKEN=your-visitors-token

NEXT_PUBLIC_POSTHOG_KEY=your-posthog-project-key
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
NEXT_PUBLIC_OPENPANEL_CLIENT_ID=your-openpanel-client-id
NEXT_PUBLIC_BENTO_SITE_UUID=your-bento-site-uuid
NEXT_PUBLIC_VISITORS_TOKEN=your-visitors-token

OPENPANEL_CLIENT_ID=your-openpanel-client-id
OPENPANEL_CLIENT_SECRET=your-openpanel-client-secret
POSTHOG_API_KEY=your-posthog-server-key
BENTO_SITE_UUID=your-bento-site-uuid
BENTO_PUBLISHABLE_KEY=your-bento-publishable-key
BENTO_SECRET_KEY=your-bento-secret-key
EMITKIT_API_KEY=emitkit_xxx
PIRSCH_ACCESS_KEY=pa_xxx

PUBLIC_POSTHOG_KEY=your-posthog-project-key
PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
PUBLIC_OPENPANEL_CLIENT_ID=your-openpanel-client-id
PUBLIC_BENTO_SITE_UUID=your-bento-site-uuid
PUBLIC_VISITORS_TOKEN=your-visitors-token

OPENPANEL_CLIENT_ID=your-openpanel-client-id
OPENPANEL_CLIENT_SECRET=your-openpanel-client-secret
POSTHOG_API_KEY=your-posthog-server-key
BENTO_SITE_UUID=your-bento-site-uuid
BENTO_PUBLISHABLE_KEY=your-bento-publishable-key
BENTO_SECRET_KEY=your-bento-secret-key
EMITKIT_API_KEY=emitkit_xxx
PIRSCH_ACCESS_KEY=pa_xxx

Verify imports

Create a small file and let TypeScript confirm the packages resolve. This example uses PostHog’s client provider; swap in the provider you installed:

import { defineEvents, noProperties } from 'trakoo';
import { createClientAnalytics } from 'trakoo/client';
import { PostHogClientProvider } from '@trakoo/posthog/client';

const events = defineEvents({
  testEvent: {
    name: 'test_event',
    category: 'engagement',
    properties: noProperties()
  }
});

const analytics = createClientAnalytics({
  events,
  providers: [
    new PostHogClientProvider({
      token: 'test'
    })
  ]
});

await analytics.track('test_event');

If your project compiles, continue to the Quick Start.