@galacha/react

v0.1.2

Published

2 months ago

React + Next.js bindings for the Galacha session replay SDK. Loads the web bundle from the CDN, exposes a tiny hooks API.

Downloads

0High
0Medium
0Low

nassdaq

galacha session-replay rrweb react nextjs logrocket

@galacha/react

React + Next.js bindings for the Galacha session replay SDK.

This package is a thin wrapper. It does not vendor rrweb or any recorder code. It lazy-loads the web UMD bundle from sdk.galacha.me at runtime and exposes a small React API.

Works in React 17+ (Vite, CRA, plain webpack)
Works in Next.js 13+ (App Router + Pages Router)
Works in Remix, TanStack Start, anywhere React renders in the browser
One Provider, one hook, one <PrivateBlock> component
Zero runtime dependencies

For React Native, use @galacha/react-native instead.

Install

npm install @galacha/react
# or
pnpm add @galacha/react
# or
yarn add @galacha/react

Quickstart

Wrap your app in <GalachaProvider>:

import { GalachaProvider } from "@galacha/react";

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <GalachaProvider projectKey={process.env.NEXT_PUBLIC_GALACHA_PROJECT_KEY!}>
      {children}
    </GalachaProvider>
  );
}

That's it. The SDK loads, recording starts, replays appear in your dashboard within a few seconds.

Next.js App Router

The Provider is already a client component ("use client" is baked into the bundle), so you can drop it directly into app/layout.tsx:

// app/layout.tsx
import { GalachaProvider } from "@galacha/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <GalachaProvider projectKey={process.env.NEXT_PUBLIC_GALACHA_PROJECT_KEY!}>
          {children}
        </GalachaProvider>
      </body>
    </html>
  );
}

The env var must be prefixed NEXT_PUBLIC_ so Next.js exposes it to the browser.

Next.js Pages Router

// pages/_app.tsx
import { GalachaProvider } from "@galacha/react";
import type { AppProps } from "next/app";

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <GalachaProvider projectKey={process.env.NEXT_PUBLIC_GALACHA_PROJECT_KEY!}>
      <Component {...pageProps} />
    </GalachaProvider>
  );
}

Vite / CRA / anywhere else

// src/main.tsx
import { createRoot } from "react-dom/client";
import { GalachaProvider } from "@galacha/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <GalachaProvider projectKey={import.meta.env.VITE_GALACHA_PROJECT_KEY}>
    <App />
  </GalachaProvider>,
);

Identifying users

Three ways to attach a user identity. Pick whichever fits your auth flow.

1. `useIdentify()` — declarative (recommended)

import { useIdentify } from "@galacha/react";

function AppShell() {
  const { user } = useAuth();

  useIdentify(user?.id, {
    email: user?.email,
    name: user?.name,
    plan: user?.plan,
  });

  return <Routes />;
}

Re-runs automatically when user.id changes. Safe to call with null when the user isn't logged in.

2. `useGalacha()` — imperative

import { useGalacha } from "@galacha/react";

function LoginForm() {
  const { identify } = useGalacha();

  const handleLogin = async (email: string, password: string) => {
    const user = await api.login(email, password);
    identify(user.id, { email: user.email });
  };

  // ...
}

3. Inline config — identify on init

<GalachaProvider
  projectKey="..."
  identifier={currentUser?.id}
  traits={{ email: currentUser?.email }}
>

Good for apps that know the user at the top of the tree before rendering.

Masking sensitive views

Use <PrivateBlock> to wrap anything you don't want captured:

import { PrivateBlock } from "@galacha/react";

<PrivateBlock>
  <CreditCardForm />
</PrivateBlock>

All inputs, textareas, and visible text inside are masked in the replay. For stronger protection (the entire DOM subtree is dropped), use block:

<PrivateBlock block>
  <SSNInput />
</PrivateBlock>

Reading live session state

import { useGalacha } from "@galacha/react";

function DebugPanel() {
  const { ready, sessionId, visitorId } = useGalacha();

  return (
    <div>
      <div>Status: {ready ? "recording" : "loading"}</div>
      <div>Session: {sessionId ?? "—"}</div>
      <div>Visitor: {visitorId ?? "—"}</div>
    </div>
  );
}

Stopping recording

On logout, or at the end of a test run:

const { stop } = useGalacha();

function handleLogout() {
  stop();
  // ...clear auth, redirect, etc.
}

Disabling in tests

<GalachaProvider projectKey="..." disabled={process.env.NODE_ENV === "test"}>

Public API

| Export | Purpose | |---|---| | <GalachaProvider> | Wraps your app, loads the SDK, calls init() | | useGalacha() | Returns { ready, identify, stop, sessionId, visitorId } | | useIdentify(userId, traits) | Declaratively identify the current user | | <PrivateBlock> | Mark a DOM subtree as private (masked in replay) | | GalachaConfig, GalachaTraits (types) | For TypeScript consumers |

What this package does NOT do

Ship the recorder. It loads sdk.galacha.me/sdk/latest/galacha.umd.js at runtime, so browser caching is shared across sites that use Galacha
Support SSR event capture. Recording only runs in the browser
Expose track() or flush(). Those are React Native features

Docs

Full documentation: https://docs.galacha.me

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@galacha/react

Install

Quickstart

Next.js App Router

Next.js Pages Router

Vite / CRA / anywhere else

Identifying users

1. useIdentify() — declarative (recommended)

2. useGalacha() — imperative

3. Inline config — identify on init

Masking sensitive views

Reading live session state

Stopping recording

Disabling in tests

Public API

What this package does NOT do

Docs

1. `useIdentify()` — declarative (recommended)

2. `useGalacha()` — imperative