@getfluxly/react

GetFluxly's React SDK. Provider and hooks that wrap @getfluxly/browser for React 18+ and React-based frameworks (Next.js, Remix, TanStack Start).

Install

npm i @getfluxly/react @getfluxly/browser react

@getfluxly/browser is a peer dependency — install it alongside.

60-second quickstart

Wrap your app in <GFluxProvider> once, then call hooks anywhere.

// app/providers.tsx (Next.js App Router)
"use client";
import { GFluxProvider } from "@getfluxly/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <GFluxProvider apiKey={process.env.NEXT_PUBLIC_GFLUX_API_KEY!}>
      {children}
    </GFluxProvider>
  );
}

// app/sign-up-button.tsx
"use client";
import { useTrack, useIdentify } from "@getfluxly/react";

export function SignUpButton() {
  const track = useTrack();
  const identify = useIdentify();

  return (
    <button onClick={async () => {
      const user = await signUp();
      identify(user.id, { email: user.email, plan: user.plan });
      track("user_signed_up", { plan: user.plan });
    }}>
      Sign up
    </button>
  );
}

That's it. Open the GetFluxly dashboard live feed and you'll see the events arrive within a second.

Configuration

<GFluxProvider> props:

| Prop | Type | Description | |---|---|---| | apiKey | string | Your GetFluxly publishable key (gflux_pub_*). Required unless client is supplied. | | apiHost | string | API base URL. Defaults to https://api.getfluxly.com. | | config | Partial<GFluxConfig> | Anything else from @getfluxly/browser's init config (autocapture toggles, consentMode, region, flushIntervalMs, etc.). | | client | GFluxBrowser \| null | Advanced. Pass an already-constructed client to fully control its lifecycle. When set, apiKey/apiHost/config are ignored. | | children | React.ReactNode | Your app tree. |

If both apiKey and client are omitted, the provider renders children but every hook returns a no-op — useful for SSR and for environments where you intentionally disable analytics.

API reference

useGFlux(): GFluxBrowser | null

Returns the raw client instance. null during SSR or before the provider mounts. Use this when you need a method that doesn't have a dedicated hook (reset, destroy, __debug).

useTrack<TEvents>(): (name, properties?) => void

Returns a stable callback that fires client.track(name, properties). Safe to put in useEffect deps without churn. The optional generic parameter unlocks IDE autocomplete:

type AppEvents = {
  user_signed_up: { plan: "free" | "pro" };
  feature_used:   { feature_name: string; ms_to_first_use: number };
};

const track = useTrack<AppEvents>();
track("user_signed_up", { plan: "pro" });   // ✓
track("user_signed_up", { plan: "gold" });  // ✗ type error
track("typo_event", {});                    // ✗ unknown event

useIdentify(): (externalId, traits?) => void

Returns a stable identify callback. Per docs/sdk-standards/identity-stitching.md, calling identify twice with different externalIds in the same session is a bug — the second call is dropped client-side with a warn log.

usePage(): (properties?) => void

Returns a stable page callback. Most apps don't need to call this manually — the browser SDK autocaptures pageviews including SPA route changes. Call it explicitly only when you want a custom pageview event with extra properties (e.g. { section: "billing" }).

useConsent()

Returns { status, optIn, optOut }. status is "unknown" | "opted_in" | "opted_out", derived from the browser SDK's persisted consent flags. "unknown" covers both the SSR path and the EU implicit-pending state where events are buffered until optIn() is called.

Errors

The browser SDK is fire-and-forget by design — track/identify/page never throw to caller code. Errors land in the configured logger (defaults to console.warn) and the __debug() counters.

The provider DOES throw at construction if apiKey is malformed. That surfaces as a render error you'll catch in development immediately.

See the closed error code list in the error taxonomy standard.

Identity model

Two-sentence summary: GetFluxly stitches three IDs (anonymous, external, previous). The browser SDK auto-assigns the anonymous ID; you set the external ID via identify() after sign-in.

Full reference: identity stitching standard.

SSR / Server Components

Every hook is SSR-safe:

• During SSR (no window), useGFlux() returns null and the action hooks (useTrack, useIdentify, usePage) return no-op functions.
• The provider wraps initGFlux in useEffect so the browser SDK boots only on the client.
• Every module that touches React state ships "use client" so Next.js's App Router treats it correctly without an explicit directive in your code.

Privacy and consent

The browser SDK respects GPC by default and shows an explicit consent banner in the EU. None of that behavior changes through this React wrapper — see @getfluxly/browser README for the full posture.

Links

• Dashboard: https://app.getfluxly.com
• Docs: https://docs.getfluxly.com/sdks/react
• Issues: https://github.com/dineshmiriyala/getfluxly/issues
• Security: see SECURITY.md