Installation

Grounded currently ships as three TypeScript packages:

@grounded/client
@grounded/tracing
@grounded/analytics

Runtime Split

@grounded/client is server-only control-plane code
@grounded/tracing is server-side instrumentation
@grounded/analytics is browser-side telemetry

They stay separate so browser apps do not pull in server-only code, and backend services do not pull in browser storage and FullStory concerns.

Runtime Requirements

Recommended runtime:

Node.js 22+ for @grounded/client and @grounded/tracing
modern browsers for @grounded/analytics
TypeScript 5.7+ if you are compiling from source

Current State

The packages are implemented inside the Grounded monorepo and prepared for npm publishing.

That means there are two practical installation modes today:

use them as workspace packages inside the monorepo
publish them from the monorepo into your own registry flow or the @grounded npm scope

Monorepo Usage

Inside the Grounded repo:

pnpm --filter @grounded/client build
pnpm --filter @grounded/tracing build
pnpm --filter @grounded/analytics build

Intended Public Install Shape

npm install @grounded/client @grounded/tracing @grounded/analytics

Build And Test

Inside the monorepo:

pnpm --filter @grounded/client test
pnpm --filter @grounded/tracing test
pnpm --filter @grounded/analytics test
pnpm test:sdk
pnpm test:sdk:integration

Package Summary

`@grounded/client`

Grounded
normalized list handling
retries and timeouts
idempotency headers on POST
GroundedApiError
GroundedJobError
typed traces, sessions, snapshots, jobs, evals, and dataset surfaces

`@grounded/tracing`

GroundedTracing
traces, spans, events, and scores
batching and shutdown flushing
masking before send
OpenAI wrapping
OpenTelemetry exporter bridge

`@grounded/analytics`

init()
identify, page, and track
stable sessionId and anonymousId
getContext() for browser-to-server correlation
optional FullStory mirror mode

Overview Authentication