feat(react)!: react server support (#235)

BREAKING CHANGES:
- All imports that were previously under the package root (`@spotify-confidence/react`) are now accessible under `@spotify-confidence/react/client`.
- Previously, when you did `useConfidence`, the returned instance would be augmented with extra hook like functions such as `useFlag`. These have been removed and you should just use the exported top level hooks.

---------

Co-authored-by: Nicklas Lundin <[email protected]>

Author: andreas-karlsson

api/react-client.d.ts

@@ -0,0 +1,55 @@
+import { ConfidenceOptions, Confidence, Context, FlagEvaluation, Value } from '@spotify-confidence/sdk';
+import { FC, PropsWithChildren, FunctionComponent, ReactNode } from 'react';
+
+declare const ManagedConfidenceProvider: FC<PropsWithChildren<{
+    options: ConfidenceOptions;
+}>>;
+/**
+ * Confidence Provider for React
+ * @public
+ */
+interface ConfidenceProvider extends FunctionComponent<{
+    confidence: Confidence;
+    children?: ReactNode;
+}> {
+    WithContext: FC<PropsWithChildren<{
+        context: Context;
+    }>>;
+}
+/**
+ * Confidence Provider for React
+ * @public
+ */
+declare const ConfidenceProvider: ConfidenceProvider;
+/**
+ * Enables using Confidence
+ * @public
+ */
+declare const useConfidence: () => Confidence;
+/**
+ * Use with given Confidence Context
+ * @public
+ */
+declare function useWithContext(context: Context, parent?: Confidence): Confidence;
+/**
+ * Use Confidence Context
+ * @public
+ */
+declare function useConfidenceContext(confidence?: Confidence): Context;
+/**
+ * Use EvaluateFlag
+ * @public */
+declare function useEvaluateFlag(path: string, defaultValue: string, confidence?: Confidence): FlagEvaluation<string>;
+declare function useEvaluateFlag(path: string, defaultValue: number, confidence?: Confidence): FlagEvaluation<number>;
+declare function useEvaluateFlag(path: string, defaultValue: boolean, confidence?: Confidence): FlagEvaluation<boolean>;
+declare function useEvaluateFlag<T extends Value>(path: string, defaultValue: T, confidence?: Confidence): FlagEvaluation<T>;
+/**
+ * Use Flag
+ * @public
+ */
+declare function useFlag(path: string, defaultValue: string, confidence?: Confidence): string;
+declare function useFlag(path: string, defaultValue: number, confidence?: Confidence): number;
+declare function useFlag(path: string, defaultValue: boolean, confidence?: Confidence): boolean;
+declare function useFlag<T extends Value>(path: string, defaultValue: T, confidence?: Confidence): T;
+
+export { ConfidenceProvider, ManagedConfidenceProvider, useConfidence, useConfidenceContext, useEvaluateFlag, useFlag, useWithContext };

api/react-server.d.ts

@@ -0,0 +1,9 @@
+import { Confidence } from '@spotify-confidence/sdk';
+import React, { ReactNode } from 'react';
+
+declare function ConfidenceProvider(props: {
+    confidence: Confidence;
+    children?: ReactNode;
+}): Promise<React.JSX.Element>;
+
+export { ConfidenceProvider };

api/react.d.ts

@@ -33,7 +33,6 @@
     "@spotify/tsconfig": "^15.0.0",
     "@swc/core": "^1.4.13",
     "@types/jest": "^29.5.3",
-    "@types/react": "^18.2.17",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "@yarnpkg/types": "^4.0.0",

package.json

@@ -16,15 +16,17 @@ yarn add @spotify-confidence/react
 
 ### Initializing the ConfidenceProvider
 
-The Confidence React integration has a Provider that needs to be initialized. It accepts a Confidence instance and should wrap your component tree.
+The Confidence React integration has a Provider that needs to be initialized. It accepts a Confidence instance and should wrap your component tree. Here's an example for client-side rendering:
 
 ```ts
-import { Confidence } from '@spotify-confidence/sdk';
+import { Confidence } from '@spotify-confidence/sdk/';
+import { ConfidenceProvider } from '@spotify-confidence/sdk/react/client';
 
+// Client-side initialization
 const confidence = Confidence.create({
   clientSecret: 'mysecret',
   region: 'eu',
-  environment: 'client',
+  environment: 'client', // Note: For client-side rendering
   timeout: 1000,
 });
 
@@ -39,6 +41,8 @@ function App() {
 }
 ```
 
+For server-side rendering setup, see the [Server-Side Rendering Support](#server-side-rendering-support) section below.
+
 Anywhere in the sub-tree under the `ConfidenceProvider` you can now access the confidence instance with the `useConfidence()` hook. The hook actually returns an instance of `ConfidenceReact` which is a wrapper around the normal `Confidence` API with some slight adaptations to integrate better with React. You can read more about the differences in the following sections.
 
 ### Managing context
@@ -66,6 +70,120 @@ The hooks are also reactive so that if the context changes, any components using
 
 If the hooks can't resolve the flag values withing the timeout specified on the Confidence instance, they will instead return the default value.
 
+### Server-Side Rendering Support (experimental)
+
+The Confidence React SDK now supports server-side rendering (SSR) and React Server Components (RSC) for instance in Next.js. The SDK provides separate entry points for client and server components:
+
+- `@spotify-confidence/react/client` - For client components
+- `@spotify-confidence/react/server` - For server components
+
+When using the SDK in a server environment:
+
+1. Create a Confidence instance for server using the React.cache as the scope in CacheOptions.
+2. Provide an accessor for the Confidence instance using `withContext`.
+3. Use direct flag evaluation in server components.
+
+Here's an example of how to use Confidence in a Next.js application:
+
+```ts
+// app/confidence.ts (Server-side configuration)
+import { Confidence } from '@spotify-confidence/sdk';
+import React from 'react';
+
+const confidence = Confidence.create({
+  clientSecret: process.env.CONFIDENCE_CLIENT_SECRET!,
+  environment: 'backend',
+  timeout: 1000,
+  logger: console,
+  cache: {
+    scope: React.cache, // Use React.cache for server-side caching
+  },
+});
+
+// Confidence accessor for use in RSC.
+export const getConfidence = (context: Context): Confidence => {
+  return confidence.withContext(context);
+};
+
+// app/components/ServerComponent.tsx
+import { cookies } from 'next/headers';
+import { getConfidence } from '../confidence';
+
+export const ServerComponent = async () => {
+  const cookieStore = await cookies();
+  const targeting_key = cookieStore.get('cnfdVisitorId')?.value; // or a unique targeting value of your choice
+  const confidence = getConfidence({ targeting_key });
+
+  // Direct flag evaluation in server components
+  const color = await confidence.getFlag('my-feature-flag.color', 'blue');
+
+  return <div style={{ color }}>Server rendered content</div>;
+};
+```
+
+#### Server and Client
+
+If you also have interactive (client side) components that benefit from feature flagging support.
+Using the pattern below in addition to the above server side example will allow you to have the flag evaluations
+seamlessly transferred from the server component to the client components.
+
+Please note:
+
+- Server components use direct flag evaluation with `evaluateFlag` or `getFlag`
+- Client components use hooks (`useFlag`, `useConfidence`) for interactive features
+- Use React.cache for efficient server-side caching
+- The SDK automatically handles synchronization between server and client
+- Mutating the context in a client side component does not affect the server side confidence instance.
+
+```tsx
+// app/layout.tsx
+import { ConfidenceProvider } from '@spotify-confidence/react/server';
+import { getConfidence } from '../confidence';
+import { ClientComponent } from 'components/ClientComponent';
+import { ServerComponent } from 'components/ServerComponent';
+
+export default async function Layout() {
+  const cookieStore = await cookies();
+  const targeting_key = cookieStore.get('cnfdVisitorId')?.value;
+  const confidence = getConfidence({ targeting_key });
+
+  return (
+    <div>
+      <ConfidenceProvider confidence={confidence}>
+        <Suspense fallback={<h1>Loading...</h1>}>
+          <ClientComponent>
+            <ServerComponent>
+              <ClientComponent />
+            </ServerComponent>
+          </ClientComponent>
+        </Suspense>
+      </ConfidenceProvider>
+    </div>
+  );
+}
+
+// app/components/ClientComponent.tsx
+('use client');
+import { useConfidence, useFlag } from '@spotify-confidence/react/client';
+
+export const ClientComponent = () => {
+  // Use hooks in client components
+  const confidence = useConfidence();
+  const fontSize = useFlag('my-feature-flag.size', 12);
+
+  return (
+    <div>
+      <div style={{ fontSize }}>Client rendered content</div>
+      <button onClick={() => confidence.setContext({ locale: 'sv-SE' })}>Choose Swedish</button>
+    </div>
+  );
+};
+```
+
+#### In-depth
+
+Coming soon.
+
 ### Tracking events
 
 The event tracking API is available on the Confidence instance as usual. See the [SDK Readme](https://github.com/spotify/confidence-sdk-js/blob/main/packages/sdk/README.md#event-tracking) for details.

packages/react/README.md

@@ -17,30 +17,43 @@
   },
   "peerDependencies": {
     "@spotify-confidence/sdk": ">=0.1.4 <=0.2.2",
-    "react": "^18.2.0"
+    "react": "^18 || ^19"
   },
   "devDependencies": {
     "@spotify-confidence/sdk": "workspace:*",
-    "react": "^18.2.0",
+    "@types/react": "^18",
+    "react": "^19",
     "rollup": "4.24.0",
     "typescript": "5.1.6"
   },
   "exports": {
-    ".": {
-      "import": "./build/index.js",
-      "types": "./build/index.d.ts"
+    "./client": {
+      "import": "./build/client.js",
+      "types": "./build/client.d.ts"
+    },
+    "./server": {
+      "import": "./build/server.js",
+      "types": "./build/server.d.ts"
     }
   },
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "exports": {
-      ".": {
-        "import": "./dist/index.mjs",
-        "require": "./dist/index.cjs",
-        "types": "./dist/index.d.ts"
+      "./client": {
+        "import": "./dist/client.mjs",
+        "require": "./dist/client.cjs",
+        "types": "./dist/client.d.ts"
+      },
+      "./server": {
+        "import": "./dist/server.mjs",
+        "require": "./dist/server.cjs",
+        "types": "./dist/server.d.ts"
       }
     }
+  },
+  "dependencies": {
+    "server-only": "^0.0.1"
   }
 }