Choose the right rollfuse SDK for the job

rollfuse ships three JavaScript packages, and the right one for a given piece of code depends on where that code runs and which kind of credential it is allowed to hold, not on which feature you want to use, since all three evaluate flags the same way.

@rollfuse/sdk-js: server-side Node.js, Service Credential

Use this in any Node.js process (an API server, a background worker, a Next.js Server Component) that can hold a Service Credential without exposing it to a client.

import { RollfuseClient } from "@rollfuse/sdk-js";

const client = new RollfuseClient({
  baseUrl: "https://api.rollfuse.com",
  credential: process.env.ROLLFUSE_CREDENTIAL!, // set before running
});

await client.start();

const result = client.evaluate("user-42", "checkout-redesign", { fallback: false });

A Service Credential can read the full Configuration and submit exposure events directly. It must never reach a browser: see Issue and revoke environment credentials for how it is issued and rotated.

@rollfuse/sdk-browser: client-side, Public Credential

Use this when evaluation needs to happen directly in the browser, for example a client-only widget with no server render step. It takes a publicCredential, a token issued from a Credential created in Public mode with config:read only, never a normal Service Credential.

npm install @rollfuse/sdk-browser

import { RollfusePublicClient } from "@rollfuse/sdk-browser";

const client = new RollfusePublicClient({
  baseUrl: "https://api.rollfuse.com",
  publicCredential: (window as any).__ROLLFUSE_PUBLIC_CREDENTIAL__, // injected by your own server-rendered template
});

await client.start();

const unsubscribe = client.subscribe(() => {
  // Configuration updated: re-evaluate and re-render
});

const result = client.evaluate("user-42", "checkout-redesign", { fallback: false });

A Public Credential can only read Configuration, so leaking it to a browser's network tab does not expose write access or other environments' data the way a Service Credential would.

@rollfuse/sdk-react: the consumption layer for React and Next.js

@rollfuse/sdk-react does not talk to the platform on its own. It wraps either of the two clients above behind RollfuseProvider, useFlag, and useFlags, and supports two modes.

npm install @rollfuse/sdk-react

Mode 1: server-evaluated props. A Next.js Server Component runs client.evaluateAll(subjectKey) from sdk-js, then passes the resulting evaluations down as plain props:

import { RollfuseProvider, useFlag } from "@rollfuse/sdk-react";

// Server Component
const evaluations = client.evaluateAll(subjectKey, { attributes: { plan: "pro" } });

function Page() {
  return (
    <RollfuseProvider evaluations={evaluations}>
      <Checkout />
    </RollfuseProvider>
  );
}

// Client Component
function Checkout() {
  const flag = useFlag<boolean>("checkout-redesign", { fallback: false });
  return flag.value ? <NewCheckout /> : <LegacyCheckout />;
}

This mode keeps the Service Credential entirely on the server: the browser only ever receives already-resolved values, never the credential itself.

Mode 2: client-driven. RollfuseProvider takes a RollfusePublicClient from sdk-browser directly, plus the subjectKey and attributes to evaluate against:

import { RollfuseProvider, useFlag, reportExposure } from "@rollfuse/sdk-react";

function App({ publicClient, subjectKey, attributes }) {
  return (
    <RollfuseProvider client={publicClient} subjectKey={subjectKey} attributes={attributes}>
      <Checkout />
    </RollfuseProvider>
  );
}

function Checkout() {
  const flag = useFlag<boolean>("checkout-redesign", { fallback: false });

  if (flag.value) {
    reportExposure("/api/rollfuse-exposure", {
      flagKey: "checkout-redesign",
      subjectKey: "user-42",
      variationKey: flag.variation_key,
      reason: flag.reason,
      configVersion: flag.config_version,
    });
  }

  return flag.value ? <NewCheckout /> : <LegacyCheckout />;
}

reportExposure posts to an endpoint your own application hosts, never straight to the platform's exposure API: your /api/rollfuse-exposure route is what forwards it server-side with a real Service Credential.

Picking one

• Server can hold a Service Credential, want the browser to see nothing but resolved values: sdk-js plus sdk-react in server-evaluated mode.
• No server render step, or evaluation genuinely needs to happen in the browser: sdk-browser, alone or wrapped by sdk-react in client-driven mode.
• Plain Node.js service, no React involved: sdk-js alone, as covered in Evaluate your first flag with sdk-js.