Lekko Next.js SDK

The Lekko Next.js SDK lets you add dynamic configuration to your Next.js applications by handling communication with Lekko and evaluation behind the scenes.

This page explains how to use the Next.js SDK. For an end-to-end tutorial, see Next.js tutorial.

Prerequisites

An existing project that uses Next.js 13.2 or newer. Alternatively, create a new Next.js project (opens in a new tab).
Set up Lekko in your project using the Get started guide.

Installation

npm install @lekko/next-sdk

Add Lekko helper to Next.js config file

In your next.config.js file, add the Lekko helper withLekkoNextConfig. This is what performs build-time checks and transformations for your lekko functions.

ℹ️

Import the Lekko helper from @lekko/next-sdk/config, not @lekko/next-sdk.

const { withLekkoNextConfig } = require("@lekko/next-sdk/config");
 
const nextConfig = {
  // Your regular Next.js configs
};
 
module.exports = withLekkoNextConfig(nextConfig);

Create lekkos (config functions)

Lekkos are config functions that you can use to read configs in your app.

For example, the following code is a simple example lekko that returns a simple .

lekko/default.ts

export function getSomeString(): string {
  return "Hi, I'm a lekko!";
}

The following lekko, which represents a simple feature flag, returns false in production environments, but true in other environments.

lekko/default.ts

export function getTestFlag({ env }: { env: string }): boolean {
  if (env === "production") {
    return false;
  }
  return true;
}

Add the Lekko provider to your app

With Next.js 13.4 (opens in a new tab), Next.js released the app router as a stable feature. There are significant differences between the pages router and the app router.

Determine which router your app uses, and select the appropriate tab below.

In /app/layout.tsx or a similar top-level layout, add LekkoNextProvider. This provider is responsible for connecting to Lekko’s services and hydrating client-side code with up-to-date config values.

/app/layout.tsx

import { LekkoNextProvider } from "@lekko/next-sdk";
 
...
 
export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body>
        <LekkoNextProvider revalidate={10}>
          {children}
        </LekkoNextProvider>
      </body>
    </html>
  );
}

Read lekkos in client components

In a client component, use the useLekkoConfig hook to use lekkos:

"use client";
 
import { useLekkoConfig } from "@lekko/next-sdk";
// Import the lekkos you previously defined
import { getTestFlag } from "@/lekko/default";
 
...
 
export default function MyClientComponent() {
  // The first argument is the lekko. The second argument is the evaluation context.
  const flag = useLekkoConfig(getTestFlag, { env: process.env.NODE_ENV });
 
  return (
    ...
  );
}

Use lekkos in server code outside of React SSR (Route Handlers, Middleware, etc.)

In order to use lekkos directly without a useLekkoConfig hook, you need to initialize global Lekko client using instrumentation hook (opens in a new tab):

instrumentation.ts

import { initLekko } from "@lekko/js-sdk";
 
export async function register() {
  await initLekko({ updateIntervalMs: 5000 });
}

Don't forget to enable instrumentation hook in your NextJS config:

next.config.mjs

const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};

Then you can use lekkos as normal functions in your route handlers:

app/api/route.ts

import { NextResponse } from "next/server";
import { getEndpointEnabled } from "@/lekko/default";
 
export async function POST(request: Request) {
    const role = ...;
 
    if (!getEndpointEnabled({ role })) {
      return NextResponse.json(
        { error: "You are not authorized to use this endpoint" },
        { status: 403 },
      );
    }
}

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)

Environment variables

For your app to connect to Lekko's services, make sure you set the NEXT_PUBLIC_LEKKO_API_KEY environment variable when building. You can generate API keys for your Lekko team on the Lekko web UI (opens in a new tab).

During local development, you don't need the API key. But for testing against live versions of your lekkos or deploying your project, you'll want to make sure that it's passed correctly.

For example, on Vercel, you can set NEXT_PUBLIC_LEKKO_API_KEY in your project → Settings → Environment variables.

What’s next

For an end-to-end tutorial, see Next.js tutorial.

React TypeScript (Client)