Replane Next.js SDK

Dynamic configuration for Next.js applications with SSR support.

Replane is a dynamic configuration manager that lets you tweak your software without running scripts or building your own admin panel. Store feature flags, rate limits, UI text, log level, rollout percentage, and more. Delegate editing to teammates and share config across services. No redeploys needed.

Why Dynamic Configuration?

- Feature flags – toggle features, run A/B tests, roll out to user segments
- Operational tuning – adjust limits, TTLs, and timeouts without redeploying
- Per-environment settings – different values for production, staging, dev
- Incident response – instantly revert to a known-good version
- Cross-service configuration – share settings with realtime sync
- Non-engineer access – safe editing with schema validation

Installation

``bash
npm install @replanejs/next


or


pnpm add @replanejs/next
`

Quick Start

$3

1. Set up ReplaneRoot in your layout:

`tsx
// app/layout.tsx
import { ReplaneRoot } from "@replanejs/next";

interface AppConfigs {
theme: { darkMode: boolean; primaryColor: string };
features: { betaEnabled: boolean };
}

export default async function RootLayout({ children }: { children: React.ReactNode }) {
return (



connection={{
baseUrl: process.env.NEXT_PUBLIC_REPLANE_BASE_URL!,
sdkKey: process.env.NEXT_PUBLIC_REPLANE_SDK_KEY!,
}}
>
{children}



);
}
`

2. Use configs in client components:

`tsx
// components/ThemeToggle.tsx
"use client";

import { useConfig } from "@replanejs/next";

export function ThemeToggle() {
const theme = useConfig<{ darkMode: boolean }>("theme");
return

;
}
`

$3

1. Set up ReplaneProvider in \_app.tsx:

`tsx
// pages/_app.tsx
import type { AppContext, AppProps } from "next/app";
import App from "next/app";
import { ReplaneProvider, getReplaneSnapshot, type ReplaneSnapshot } from "@replanejs/next";

interface AppConfigs {
theme: { darkMode: boolean; primaryColor: string };
features: { betaEnabled: boolean };
}

interface AppPropsWithReplane extends AppProps {
replaneSnapshot: ReplaneSnapshot;
}

export default function MyApp({ Component, pageProps, replaneSnapshot }: AppPropsWithReplane) {
return (
snapshot={replaneSnapshot}
connection={{
baseUrl: process.env.NEXT_PUBLIC_REPLANE_BASE_URL!,
sdkKey: process.env.NEXT_PUBLIC_REPLANE_SDK_KEY!,
}}
>


);
}

// Fetch Replane snapshot for all pages
MyApp.getInitialProps = async (appContext: AppContext) => {
const appProps = await App.getInitialProps(appContext);

const replaneSnapshot = await getReplaneSnapshot({
connection: {
baseUrl: process.env.REPLANE_BASE_URL!,
sdkKey: process.env.REPLANE_SDK_KEY!,
},
});

return { ...appProps, replaneSnapshot };
};
`

2. Use configs in any component:

`tsx
// components/FeatureFlag.tsx
import { useConfig } from "@replanejs/next";

export function FeatureFlag() {
const features = useConfig<{ betaEnabled: boolean }>("features");
return features.betaEnabled ? : null;
}
`

Typed Hooks (Recommended)

For better type safety and autocomplete, create typed hooks for your application:

1. Define your config types:

`ts
// replane/types.ts
export interface AppConfigs {
theme: {
darkMode: boolean;
primaryColor: string;
};
features: {
betaEnabled: boolean;
maxItems: number;
};
}
`

2. Create typed hooks:

`ts
// replane/hooks.ts
import { createConfigHook, createReplaneHook } from "@replanejs/next";
import type { AppConfigs } from "./types";

// Typed hook for accessing individual configs
export const useAppConfig = createConfigHook();

// Typed hook for accessing the Replane client
export const useAppReplane = createReplaneHook();
`

3. Use in components:

`tsx
// components/ConfigDisplay.tsx
"use client";

import { useAppConfig, useAppReplane } from "@/replane/hooks";

export function ConfigDisplay() {
// Config names autocomplete, values are fully typed
const theme = useAppConfig("theme");
// theme.darkMode is boolean, theme.primaryColor is string

// Or use the client directly for more control
const replane = useAppReplane();
const snapshot = replane.getSnapshot();

return

;
}
`

Provider Props

| Prop | Type | Required | Description |
| ------------ | ------------------------- | -------- | ------------------------------------------------------- |
| connection | ConnectOptions | No | Connection options (see below) |
| defaults | Record | No | Default values if server is unavailable |
| context | Record | No | Default context for override evaluations |
| snapshot | ReplaneSnapshot | No | Snapshot for SSR hydration |
| logger | ReplaneLogger | No | Custom logger (default: console) |

Connection Options

The connection prop accepts the following options:

| Option | Type | Required | Description |
| --------------------- | --------------------- | -------- | ---------------------------------------- |
| baseUrl | string | Yes | Replane server URL |
| sdkKey | string | Yes | SDK key for authentication |
| connectTimeoutMs | number | No | SDK connection timeout (default: 5000) |
| requestTimeoutMs | number | No | Timeout for SSE requests (default: 2000) |
| retryDelayMs | number | No | Base delay between retries (default: 200)|
| inactivityTimeoutMs | number | No | SSE inactivity timeout (default: 30000) |
| fetchFn | typeof fetch | No | Custom fetch implementation |

See @replanejs/sdk documentation for more details.

API Reference

$3

#### ReplaneRoot

Server component for App Router that fetches configs and provides them to the app.

`tsx

connection={{
baseUrl: string;
sdkKey: string;
}}
>
{children}

`

#### ReplaneProvider

Client-side provider for Pages Router or custom setups.

`tsx
snapshot={replaneSnapshot}
connection={{
baseUrl: string;
sdkKey: string;
}}
>
{children}

`

$3

#### useConfig(name: string): T

Returns the value of a config by name. Re-renders when the config changes.

`tsx
const theme = useConfig<{ darkMode: boolean }>("theme");
`

#### useReplane(): Replane

Returns the Replane client instance for advanced usage.

`tsx
const client = useReplane();
const snapshot = client.getSnapshot();
const theme = client.get("theme");
`

#### createConfigHook()

Creates a typed version of useConfig for your config schema.

`tsx
const useAppConfig = createConfigHook();
const theme = useAppConfig("theme"); // fully typed
`

#### createReplaneHook()

Creates a typed version of useReplane for your config schema.

`tsx
const useAppReplane = createReplaneHook();
const client = useAppReplane(); // client.get("theme") is typed
`

$3

#### getReplaneSnapshot(options): Promise>

Fetches a snapshot of all configs. Use in getServerSideProps, getStaticProps, or getInitialProps.

`tsx
const snapshot = await getReplaneSnapshot({
connection: {
baseUrl: process.env.REPLANE_BASE_URL!,
sdkKey: process.env.REPLANE_SDK_KEY!,
},
// by default, getReplaneSnapshot will reuse the created client for 60 seconds for fast subsequent calls, the client will be syncing with the server in the background during this time
keepAliveMs: 60_000,
});
``

Examples

See the examples directory for complete working examples:

- next-app-router - App Router with ReplaneRoot
- next-pages-router - Pages Router with getInitialProps

Community

Have questions or want to discuss Replane? Join the conversation in GitHub Discussions.

License

MIT