Lekko React SDK

The Lekko React SDK lets you add dynamic configuration to your React apps.

This SDK is intended to be used with Lekko’s code transformation tools. Make sure your project is set up with Lekko by following our Getting Started guide.

Prerequisites

An existing project using React 18.2 or newer.
Set up Lekko in your project using the Get started guide.

Install

In your terminal, run the following:

npm install @lekko/react-sdk

Set up the provider

Add the LekkoConfigProvider to your app. Place it high in the component tree to ensure that Lekko hooks function correctly in all downstream components.

Example: src/App.tsx

import { LekkoConfigProvider } from "@lekko/react-sdk";
 
const App = () => {
  return (
    <LekkoConfigProvider>
      {/* Your application components go here */}
    </LekkoConfigProvider>
  );
}

The provider automatically attempts to read Lekko environment variables for popular frameworks. If you encounter issues with missing environment variables, explicitly pass them using the settings prop.

Define lekkos

Create your dynamic configurations in files within the lekko/ folder.

For example:

src/lekko/default.ts

/** Test feature flag description */
export function getMyFeatureFlag({ userId }: { userId: number }): boolean {
  if (userId === 15) {
    return true
  }
  return false
}
 
/** Config for controlling the text on the title component */
export function getTitle({ env }: { env: string }): string {
  if (env === "production") {
    return "Hello, Lekko!"
  }
  return "Dev time"
}

Use the Lekko hook

Use useLekkoConfig to evaluate lekkos with specific contexts.

⚠️

Make sure that the hook is being used in components under the LekkoConfigProvider!

import { useLekkoConfig } from "@lekko/react-sdk";
import { getMyFeatureFlag, getTitle } from "../lekko/default";
 
export function MyComponent() {
  const featureFlag = useLekkoConfig(getMyFeatureFlag, { userId: 15 });
  const title = useLekkoConfig(getTitle, { env: process.env.NODE_ENV });
 
  return (
    // Your component implementation
  );
}

Install build plugins

While the SDK is responsible for communicating with Lekko's services and evaluating lekkos, build-time code transformations are handled by separate plugins that depend on your project's build setup.

Install the appropriate Lekko build tool plugin for your project as a dev dependency and follow the setup instructions:

For Vite: @lekko/vite-plugin (opens in a new tab)
For Webpack: @lekko/webpack-loader (opens in a new tab)

⚠️

If your app was initialized using create-react-app, you will need to eject (opens in a new tab) in order to access the underlying Webpack configs. Note that CRA is no longer actively maintained (opens in a new tab). You may want to consider alternative frameworks like Vite (opens in a new tab).

Install ESLint plugin

Because lekkos are subject to certain syntax limitations for now (e.g. no loops), we publish an ESLint plugin to help you catch errors earlier and provide quick-fixes if applicable.

You can find instructions and documentation here: @lekko/eslint-plugin (opens in a new tab)

Suspenseful initialization

By default, LekkoConfigProvider initializes lazily in production which may cause a flicker on initial load if there are changes to the deployed configs. To avoid this flicker, use the LekkoConfigProviderSuspend for suspenseful initialization.

import { Suspense } from "react";
import { LekkoConfigProviderSuspend } from "@lekko/react-sdk";
 
const App = () => {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <LekkoConfigProviderSuspend>
        {/* Your application components go here */}
      </LekkoConfigProviderSuspend>
    </Suspense>
  );
}

This method integrates with React’s Suspense (opens in a new tab), allowing you to display a fallback UI during the initialization process.

Go Next.js