Skip to content

Latest commit

 

History

History

react-universal

README.md

LaunchDarkly React Universal SDK

NPM Actions Status Documentation NPM NPM

Caution

This library is a beta version and should not be considered ready for production use while this message is visible.

Features

  • Supports both React Server Components and Client Components
  • Idiomatic server side rendering
  • Bootstrapping out of the box

Install

# npm
npm i @launchdarkly/react-universal-sdk

# yarn
yarn add -D @launchdarkly/react-universal-sdk

Server API

  • initNodeSdk - Initializes the Node SDK on startup.

  • getBootstrap - Produces suitable bootstrap the js sdk.

  • useLDClientRsc - Gets a suitable ld client for Server Components.

Client API

  • LDProvider - The react context provider.

  • useLDClient - Gets a suitable ld client for Client Components.

Usage

  1. On server start, initialize the Node Server SDK. If you are using NextJS App Router, do this in instrumentation.ts. You'll need to enable the instrumentationHook:
import { initNodeSdk } from '@launchdarkly/react-universal-sdk/server';

export async function register() {
  await initNodeSdk();
}
  1. At the application root, render the LDProvider with your LDContext and bootstrap. In App Router, do this in the root layout:
export default async function RootLayout({
  children,
}: Readonly<{
  children: ReactNode;
}>) {
  // You must supply an LDContext. For example, here getLDContext
  // inspects cookies and defaults to anonymous.
  const context = getLDContext();

  // A bootstrap is required to initialize LDProvider.
  const bootstrap = await getBootstrap(context);

  return (
    <html lang="en">
      <body className={inter.className}>
        <LDProvider context={context} options={{ bootstrap }}>
          {children}
        </LDProvider>
      </body>
    </html>
  );
}
  1. Server Components must use the async useLDClientRsc function:
// You should use your own getLDContext function.
import { getLDContext } from '@/app/utils';

import { useLDClientRsc } from '@launchdarkly/react-universal-sdk/server';

export default async function ServerComponent() {
  const ldc = await useLDClientRsc(getLDContext());
  const flagValue = ldc.variation('my-boolean-flag-1');

  return <>Server Component: {flagValue.toString()}</>;
}

Client Components must use the useLDClient hook:

'use client';

import { useLDClient } from '@launchdarkly/react-universal-sdk/client';

export default function ClientComponent() {
  const ldc = useLDClient();
  const flagValue = ldc.variation('my-boolean-flag-1');

  return <p>Client Component: {flagValue.toString()}</p>;
}

You will see both Server and Client Components are rendered on the server (view source on your browser). However, only Client Components will respond to live changes because Server Components are excluded from the client bundle.

Verifying SDK build provenance with the SLSA framework

LaunchDarkly uses the SLSA framework (Supply-chain Levels for Software Artifacts) to help developers make their supply chain more secure by ensuring the authenticity and build integrity of our published SDK packages. To learn more, see the provenance guide.

About LaunchDarkly

  • LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can:
    • Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
    • Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?).
    • Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file.
    • Grant access to certain features based on user attributes, like payment plan (eg: users on the ‘gold’ plan get access to more features than users in the ‘silver’ plan).
    • Disable parts of your application to facilitate maintenance, without taking everything offline.
  • LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Read our documentation for a complete list.
  • Explore LaunchDarkly