npm - @replanejs/next - Versions diffs - 0.7.3 → 0.7.5 - Mend

@replanejs/next 0.7.3 → 0.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/README.md CHANGED Viewed

@@ -2,424 +2,288 @@
 Next.js SDK for Replane - feature flags and remote configuration with SSR support.
-## Features
-- **SSR Hydration**: Fetch configs on the server, instantly hydrate on the client
-- **Zero Loading States**: Users see correct feature flags immediately
-- **Real-time Updates**: Optional live connection for instant config changes
-- **Type-safe**: Full TypeScript support with generics
-- **Next.js Optimized**: Works with App Router, Pages Router, and Server Components
 ## Installation
 ```bash
 npm install @replanejs/next
 # or
 pnpm add @replanejs/next
-# or
-yarn add @replanejs/next
 ```
 ## Quick Start
-### 1. Set up environment variables
+### App Router (Recommended)
-```env
-# Server-side (not exposed to browser)
-REPLANE_BASE_URL=https://your-replane-instance.com
-REPLANE_SDK_KEY=rp_your_server_sdk_key
-# Client-side (exposed to browser, for real-time updates)
-NEXT_PUBLIC_REPLANE_BASE_URL=https://your-replane-instance.com
-NEXT_PUBLIC_REPLANE_SDK_KEY=rp_your_client_sdk_key
-```
-### 2. Create the provider in your layout (App Router)
+**1. Set up ReplaneRoot in your layout:**
 ```tsx
 // app/layout.tsx
-import { getReplaneSnapshot } from "@replanejs/next/server";
-import { ReplaneNextProvider } from "@replanejs/next";
-export default async function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const snapshot = await getReplaneSnapshot({
-    baseUrl: process.env.REPLANE_BASE_URL!,
-    sdkKey: process.env.REPLANE_SDK_KEY!,
-  });
+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 (
     <html lang="en">
       <body>
-        <ReplaneNextProvider
-          snapshot={snapshot}
-          connection={{
+        <ReplaneRoot<AppConfigs>
+          options={{
             baseUrl: process.env.NEXT_PUBLIC_REPLANE_BASE_URL!,
             sdkKey: process.env.NEXT_PUBLIC_REPLANE_SDK_KEY!,
           }}
         >
           {children}
-        </ReplaneNextProvider>
+        </ReplaneRoot>
       </body>
     </html>
   );
 }
 ```
-### 3. Use configs in your components
+**2. Use configs in client components:**
 ```tsx
-// app/components/feature.tsx
+// components/ThemeToggle.tsx
 "use client";
 import { useConfig } from "@replanejs/next";
-export function FeatureComponent() {
-  const isEnabled = useConfig<boolean>("my-feature");
-  const maxItems = useConfig<number>("max-items");
-  if (!isEnabled) {
-    return null;
-  }
-  return <div>Feature enabled! Max items: {maxItems}</div>;
+export function ThemeToggle() {
+  const theme = useConfig<{ darkMode: boolean }>("theme");
+  return <div>{theme.darkMode ? "Dark Mode" : "Light Mode"}</div>;
 }
 ```
-## API Reference
-### Server Functions
-#### `getReplaneSnapshot(options)`
+### Pages Router
-Fetches configs from Replane and returns a serializable snapshot for client-side hydration.
+**1. Set up ReplaneProvider in _app.tsx:**
 ```tsx
-import { getReplaneSnapshot } from "@replanejs/next/server";
-const snapshot = await getReplaneSnapshot({
-  // Required
-  baseUrl: "https://your-replane-instance.com",
-  sdkKey: "rp_your_sdk_key",
-  // Optional
-  fetchFn: customFetch, // Custom fetch for caching
-  requestTimeoutMs: 2000, // Request timeout (default: 2000)
-  initializationTimeoutMs: 5000, // Init timeout (default: 5000)
-  context: { userId: "123" }, // Context for override evaluation
-  required: ["feature-a", "feature-b"], // Required configs
-  fallbacks: { "feature-a": false }, // Fallback values
-});
-```
-#### `getConfig(options)`
-Get a single config value directly on the server.
-```tsx
-import { getConfig } from "@replanejs/next/server";
+// pages/_app.tsx
+import type { AppContext, AppProps } from "next/app";
+import App from "next/app";
+import { ReplaneProvider, getReplaneSnapshot, type ReplaneSnapshot } from "@replanejs/next";
-const maintenanceMode = await getConfig<boolean>({
-  name: "maintenance-mode",
-  baseUrl: process.env.REPLANE_BASE_URL!,
-  sdkKey: process.env.REPLANE_SDK_KEY!,
-  context: { region: "us-east" },
-});
+interface AppConfigs {
+  theme: { darkMode: boolean; primaryColor: string };
+  features: { betaEnabled: boolean };
+}
-if (maintenanceMode) {
-  return <MaintenancePage />;
+interface AppPropsWithReplane extends AppProps {
+  replaneSnapshot: ReplaneSnapshot<AppConfigs>;
 }
-```
-### Client Components
+export default function MyApp({ Component, pageProps, replaneSnapshot }: AppPropsWithReplane) {
+  return (
+    <ReplaneProvider
+      snapshot={replaneSnapshot}
+      options={{
+        baseUrl: process.env.NEXT_PUBLIC_REPLANE_BASE_URL!,
+        sdkKey: process.env.NEXT_PUBLIC_REPLANE_SDK_KEY!,
+      }}
+    >
+      <Component {...pageProps} />
+    </ReplaneProvider>
+  );
+}
-#### `ReplaneNextProvider`
+// Fetch Replane snapshot for all pages
+MyApp.getInitialProps = async (appContext: AppContext) => {
+  const appProps = await App.getInitialProps(appContext);
-Main provider component for SSR hydration.
+  const replaneSnapshot = await getReplaneSnapshot<AppConfigs>({
+    baseUrl: process.env.REPLANE_BASE_URL!,
+    sdkKey: process.env.REPLANE_SDK_KEY!,
+  });
-```tsx
-import { ReplaneNextProvider } from "@replanejs/next";
-<ReplaneNextProvider
-  snapshot={snapshot} // Required: from getReplaneSnapshot()
-  connection={{
-    // Optional: for real-time updates
-    baseUrl: "https://...",
-    sdkKey: "rp_...",
-    requestTimeoutMs: 2000,
-    retryDelayMs: 200,
-    inactivityTimeoutMs: 30000,
-  }}
-  context={{ userId: "123" }} // Optional: override context on client
->
-  {children}
-</ReplaneNextProvider>;
+  return { ...appProps, replaneSnapshot };
+};
 ```
-#### `ReplaneScriptProvider`
-Alternative hydration pattern using embedded scripts.
+**2. Use configs in any component:**
 ```tsx
-// In layout (Server Component)
-import { getReplaneSnapshotScript, ReplaneScriptProvider } from "@replanejs/next";
-export default async function RootLayout({ children }) {
-  const snapshot = await getReplaneSnapshot({ ... });
+// components/FeatureFlag.tsx
+import { useConfig } from "@replanejs/next";
-  return (
-    <html>
-      <head>
-        <script
-          dangerouslySetInnerHTML={{
-            __html: getReplaneSnapshotScript(snapshot),
-          }}
-        />
-      </head>
-      <body>
-        <ReplaneScriptProvider connection={{ baseUrl, sdkKey }}>
-          {children}
-        </ReplaneScriptProvider>
-      </body>
-    </html>
-  );
+export function FeatureFlag() {
+  const features = useConfig<{ betaEnabled: boolean }>("features");
+  return features.betaEnabled ? <BetaFeature /> : null;
 }
 ```
-### Hooks
+## Typed Hooks (Recommended)
-#### `useConfig<T>(name, options?)`
+For better type safety and autocomplete, create typed hooks for your application:
-Subscribe to a specific config with reactive updates.
+**1. Define your config types:**
-```tsx
-import { useConfig } from "@replanejs/next";
+```ts
+// replane/types.ts
+export interface AppConfigs {
+  theme: {
+    darkMode: boolean;
+    primaryColor: string;
+  };
+  features: {
+    betaEnabled: boolean;
+    maxItems: number;
+  };
+}
+```
-function MyComponent() {
-  // Basic usage
-  const feature = useConfig<boolean>("feature-flag");
+**2. Create typed hooks:**
-  // With context override
-  const price = useConfig<number>("pricing", {
-    context: { plan: "premium" },
-  });
+```ts
+// replane/hooks.ts
+import { createConfigHook, createReplaneHook } from "@replanejs/next";
+import type { AppConfigs } from "./types";
-  return <div>{feature ? "Enabled" : "Disabled"}</div>;
-}
-```
+// Typed hook for accessing individual configs
+export const useAppConfig = createConfigHook<AppConfigs>();
-#### `useReplane()`
+// Typed hook for accessing the Replane client
+export const useAppReplane = createReplaneHook<AppConfigs>();
+```
-Access the underlying Replane client.
+**3. Use in components:**
 ```tsx
-import { useReplane } from "@replanejs/next";
+// components/ConfigDisplay.tsx
+"use client";
-function MyComponent() {
-  const { client } = useReplane();
+import { useAppConfig, useAppReplane } from "@/replane/hooks";
-  // Access client methods
-  const snapshot = client.getSnapshot();
+export function ConfigDisplay() {
+  // Config names autocomplete, values are fully typed
+  const theme = useAppConfig("theme");
+  // theme.darkMode is boolean, theme.primaryColor is string
-  return <div>...</div>;
+  // Or use the client directly for more control
+  const replane = useAppReplane();
+  const snapshot = replane.getSnapshot();
+  return <div style={{ color: theme.primaryColor }}>...</div>;
 }
 ```
-## Advanced Usage
+## API Reference
-### Next.js Caching
+### Components
-Use Next.js fetch caching with `getReplaneSnapshot`:
+#### `ReplaneRoot`
-```tsx
-// ISR: Revalidate every 60 seconds
-const snapshot = await getReplaneSnapshot({
-  baseUrl: process.env.REPLANE_BASE_URL!,
-  sdkKey: process.env.REPLANE_SDK_KEY!,
-  fetchFn: (url, init) =>
-    fetch(url, {
-      ...init,
-      next: { revalidate: 60 },
-    }),
-});
-```
+Server component for App Router that fetches configs and provides them to the app.
 ```tsx
-// On-demand revalidation with tags
-const snapshot = await getReplaneSnapshot({
-  baseUrl: process.env.REPLANE_BASE_URL!,
-  sdkKey: process.env.REPLANE_SDK_KEY!,
-  fetchFn: (url, init) =>
-    fetch(url, {
-      ...init,
-      next: { tags: ["replane-config"] },
-    }),
-});
-// In a server action or route handler:
-// revalidateTag('replane-config');
+<ReplaneRoot<AppConfigs>
+  options={{
+    baseUrl: string;
+    sdkKey: string;
+    // ... other ReplaneClientOptions
+  }}
+>
+  {children}
+</ReplaneRoot>
 ```
-### Static Snapshot (No Real-time Updates)
+#### `ReplaneProvider`
-For static sites or when real-time updates aren't needed:
+Client-side provider for Pages Router or custom setups.
 ```tsx
-<ReplaneNextProvider snapshot={snapshot}>
-  {/* No connection prop = no live updates */}
+<ReplaneProvider
+  snapshot={replaneSnapshot}
+  options={{
+    baseUrl: string;
+    sdkKey: string;
+  }}
+>
   {children}
-</ReplaneNextProvider>
+</ReplaneProvider>
 ```
-### Pages Router Support
+### Hooks
-```tsx
-// pages/_app.tsx
-import { ReplaneNextProvider } from "@replanejs/next";
-import type { AppProps } from "next/app";
+#### `useConfig<T>(name: string): T`
-export default function App({ Component, pageProps }: AppProps) {
-  return (
-    <ReplaneNextProvider
-      snapshot={pageProps.replaneSnapshot}
-      connection={{
-        baseUrl: process.env.NEXT_PUBLIC_REPLANE_BASE_URL!,
-        sdkKey: process.env.NEXT_PUBLIC_REPLANE_SDK_KEY!,
-      }}
-    >
-      <Component {...pageProps} />
-    </ReplaneNextProvider>
-  );
-}
-```
+Returns the value of a config by name. Re-renders when the config changes.
 ```tsx
-// pages/index.tsx
-import { getReplaneSnapshot } from "@replanejs/next/server";
-import type { GetServerSideProps } from "next";
+const theme = useConfig<{ darkMode: boolean }>("theme");
+```
-export const getServerSideProps: GetServerSideProps = async () => {
-  const replaneSnapshot = await getReplaneSnapshot({
-    baseUrl: process.env.REPLANE_BASE_URL!,
-    sdkKey: process.env.REPLANE_SDK_KEY!,
-  });
+#### `useReplane<T>(): ReplaneClient<T>`
-  return {
-    props: { replaneSnapshot },
-  };
-};
+Returns the Replane client instance for advanced usage.
+```tsx
+const client = useReplane<AppConfigs>();
+const snapshot = client.getSnapshot();
+const theme = client.get("theme");
 ```
-### Context-based Overrides
+#### `createConfigHook<T>()`
-Pass user context for personalized config values:
+Creates a typed version of `useConfig` for your config schema.
 ```tsx
-// Server-side: include context in snapshot
-const snapshot = await getReplaneSnapshot({
-  baseUrl: process.env.REPLANE_BASE_URL!,
-  sdkKey: process.env.REPLANE_SDK_KEY!,
-  context: {
-    userId: user.id,
-    plan: user.subscription,
-    country: user.country,
-  },
-});
-// Client-side: override or extend context
-<ReplaneNextProvider
-  snapshot={snapshot}
-  context={{
-    // Add client-specific context
-    browser: navigator.userAgent,
-    screenSize: window.innerWidth > 768 ? "desktop" : "mobile",
-  }}
->
-  {children}
-</ReplaneNextProvider>
+const useAppConfig = createConfigHook<AppConfigs>();
+const theme = useAppConfig("theme"); // fully typed
 ```
-### Required Configs
+#### `createReplaneHook<T>()`
-Ensure specific configs are loaded before rendering:
+Creates a typed version of `useReplane` for your config schema.
 ```tsx
-const snapshot = await getReplaneSnapshot({
-  baseUrl: process.env.REPLANE_BASE_URL!,
-  sdkKey: process.env.REPLANE_SDK_KEY!,
-  required: ["critical-feature", "api-endpoint"],
-  // Or with default values:
-  required: {
-    "critical-feature": true,
-    "api-endpoint": "https://default.api.com",
-  },
-});
+const useAppReplane = createReplaneHook<AppConfigs>();
+const client = useAppReplane(); // client.get("theme") is typed
 ```
-### Error Handling with Fallbacks
+### Functions
-Provide fallback values for resilience:
+#### `getReplaneSnapshot<T>(options): Promise<ReplaneSnapshot<T>>`
+Fetches a snapshot of all configs. Use in `getServerSideProps`, `getStaticProps`, or `getInitialProps`.
 ```tsx
-const snapshot = await getReplaneSnapshot({
+const snapshot = await getReplaneSnapshot<AppConfigs>({
   baseUrl: process.env.REPLANE_BASE_URL!,
   sdkKey: process.env.REPLANE_SDK_KEY!,
-  fallbacks: {
-    "feature-flag": false,
-    "max-items": 10,
-    "api-endpoint": "https://fallback.api.com",
-  },
+  cacheTtlMs: 60_000, // optional, default 60 seconds
 });
 ```
-## TypeScript
+#### `clearSnapshotCache(): Promise<void>`
-Define your config types for full type safety:
+Clears the internal client cache. Useful for testing.
 ```tsx
-// types/replane.ts
-export interface ReplaneConfigs {
-  "feature-flag": boolean;
-  "max-items": number;
-  "api-endpoint": string;
-  theme: {
-    primaryColor: string;
-    darkMode: boolean;
-  };
-}
+await clearSnapshotCache();
 ```
-```tsx
-// Use with generics
-import type { ReplaneConfigs } from "./types/replane";
+## Environment Variables
-const snapshot = await getReplaneSnapshot<ReplaneConfigs>({
-  baseUrl: process.env.REPLANE_BASE_URL!,
-  sdkKey: process.env.REPLANE_SDK_KEY!,
-});
+```env
+# Server-side only (for SSR/SSG)
+REPLANE_BASE_URL=https://api.replane.io
+REPLANE_SDK_KEY=your-sdk-key
-// In components
-const theme = useConfig<ReplaneConfigs["theme"]>("theme");
+# Client-side (for live updates)
+NEXT_PUBLIC_REPLANE_BASE_URL=https://api.replane.io
+NEXT_PUBLIC_REPLANE_SDK_KEY=your-sdk-key
 ```
-## Why SSR Hydration?
-The snapshot pattern minimizes latency by:
-1. **Server Fetch**: Configs are fetched during SSR (no client-side request delay)
-2. **Instant Hydration**: Client instantly has all config values (no loading states)
-3. **Optional Live Updates**: Real-time connection established after hydration
-This means users see correct feature flags immediately without any loading states or flashes of incorrect content.
+## Examples
-## Requirements
+See the [examples](./examples) directory for complete working examples:
-- Next.js >= 13.0.0
-- React >= 18.0.0
-- Node.js >= 18.0.0
+- **[next-app-router](./examples/next-app-router)** - App Router with ReplaneRoot
+- **[next-pages-router](./examples/next-pages-router)** - Pages Router with getInitialProps
 ## License