Installation

Build and install the local packages

Public npm and CDN availability is not assumed. Build the local distribution in the Realanalytics repository, then install its tarballs in the site you want to track.

# In the Realanalytics repository
bun run pack:local

# In your site repository; use the current filenames from manifest.json
npm install /path/to/realanalytics/dist/local-packages/realanalytics-sdk-0.1.0.tgz

# The CLI, for schema and dashboard deploys
npm install --save-dev /path/to/realanalytics/dist/local-packages/realanalytics-0.1.0.tgz

dist/local-packages/manifest.json records package versions and files. The same directory holds the server SDK tarball for backend conversions. Copy the browser bundle from it if the site has no build step.

Run the installed CLI with npx --no-install realanalytics, as in the Quick Start. Without the local install, omitting --no-install would ask npm to download an unrelated package of that name from the public registry.

Next.js setup

The SDK uses browser APIs (window and localStorage), so initialize it in client code.

// components/analytics-provider.tsx
'use client'

import { createClient } from '@realanalytics/sdk'

export const analytics = createClient({
  publicKey: process.env.NEXT_PUBLIC_REALANALYTICS_KEY!,
  endpoint: process.env.NEXT_PUBLIC_REALANALYTICS_INGEST_URL!,
})

export function AnalyticsProvider() {
  return null
}

Do not call shutdown() from this singleton component's effect cleanup. React Strict Mode can run a development cleanup while the app still expects the module-level client to remain active. Reserveshutdown() for the real lifetime boundary of a client you intentionally created and own.

// app/layout.tsx
import { AnalyticsProvider } from '@/components/analytics-provider'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <AnalyticsProvider />
      </body>
    </html>
  )
}

React / Vite setup

// src/analytics.ts
import { createClient } from '@realanalytics/sdk'

export const analytics = createClient({
  publicKey: import.meta.env.VITE_REALANALYTICS_KEY,
  endpoint: import.meta.env.VITE_REALANALYTICS_INGEST_URL,
})

Copy-paste browser script

For sites without a JavaScript build, install the queue before the asynchronous browser bundle:

<script>
  window.realanalytics = window.realanalytics || function () {
    (window.realanalytics.q = window.realanalytics.q || []).push(arguments)
  }
</script>
<script
  async
  src="/vendor/realanalytics/browser.global.js"
  data-public-key="pk_live_xxx"
  data-endpoint="https://your-ingest-host.example"
></script>

Collection remains denied until your consent manager records a decision. Serve the bundle copied from dist/local-packages/browser.global.jsat the path above and replace the endpoint placeholder. See the browser and consent guide for CMP mapping, local verification, and the complete queued API.

Environment variables

Always set the endpoint explicitly, and take the key and the endpoint from the same environment's dashboard Install page. See the environment table.

Next steps

• SDK Configuration
• Browser & Consent
• Tracking Events
• Autocapture