feat: Added react-universal code. (#493)

Co-authored-by: Cody De Arkland <[email protected]>

Author: yusinto

.eslintrc.js

@@ -13,6 +13,7 @@ module.exports = {
     '**/dist/**',
     '**/vercel/examples/**',
     '**/react-native/example/**',
+    '**/react-universal/example/**',
     '**/fromExternal/**',
   ],
   rules: {
@@ -41,10 +42,10 @@ module.exports = {
     'import/no-cycle': 'error',
     'import/no-useless-path-segments': 'error',
     'import/no-duplicates': 'error',
+    'import/prefer-default-export': 'off',
     'jest/no-disabled-tests': 'warn',
     'jest/no-focused-tests': 'error',
     'jest/no-identical-title': 'error',
-    // 'jest/prefer-to-have-length': 'warn',
     'jest/valid-expect': 'error',
   },
   globals: {

.github/workflows/release-please.yml

@@ -343,7 +343,6 @@ jobs:
     permissions:
       id-token: write
       contents: write
-    # HACK: react-universal sdk is not ready for release yet.
     if: false #${{ needs.release-please.outputs.package-react-universal-release == 'true' }}
     steps:
       - uses: actions/checkout@v4

package.json

@@ -13,6 +13,7 @@
     "packages/sdk/react-native",
     "packages/sdk/react-native/example",
     "packages/sdk/react-universal",
+    "packages/sdk/react-universal/example",
     "packages/sdk/vercel",
     "packages/sdk/akamai-base",
     "packages/sdk/akamai-base/example",

packages/sdk/react-native/example/README.md

@@ -14,7 +14,7 @@ yarn && yarn build
 MOBILE_KEY=abcdef12456
 ```
 
-3. Replace `dev-test-flag` with your flag key in `src/welcome.tsx`.
+3. Replace `my-boolean-flag-1` with your flag key in `src/welcome.tsx`.
 
 4. Run the app:
 

packages/sdk/react-universal/.eslintignore

@@ -0,0 +1 @@
+example

packages/sdk/react-universal/README.md

@@ -9,62 +9,49 @@
 > [!CAUTION]
 > This library is a beta version and should not be considered ready for production use while this message is visible.
 
-> **An idiomatic LaunchDarkly SDK which supports RSC, server side rendering and bootstrapping** :clap:
+## Features
 
-This SDK supports:
+- Supports both React Server Components and Client Components
+- Idiomatic server side rendering
+- Bootstrapping out of the box
 
-- React Server Components
-- Server side rendering
-- Bootstrapping
-
-## Installation
+## Install
 
 ```shell
 # npm
-npm i @launchdarkly/react-universal-sdk --save-dev
+npm i @launchdarkly/react-universal-sdk
 
 # yarn
 yarn add -D @launchdarkly/react-universal-sdk
 ```
 
-### Server API
+## Server API
 
-- `initNodeSdk` - Initializes the Node SDK on server startup using the [instrumentation hook](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation)
+- `initNodeSdk` - Initializes the Node SDK on startup.
 
-- `getBootstrap` - Returns a json suitable for bootstrapping the js sdk.
+- `getBootstrap` - Produces suitable bootstrap the js sdk.
 
-- `useLDClientRsc` - Use this to get an ldClient for Server Components.
+- `useLDClientRsc` - Gets a suitable ld client for Server Components.
 
-### Client API
+## Client API
 
 - `LDProvider` - The react context provider.
 
-- `useLDClient` - Use this to get an ldClient for Client Components.
+- `useLDClient` - Gets a suitable ld client for Client Components.
 
 ## Usage
 
-1. Enable [instrumentationHook](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) in `next.config.mjs`:
+1. On server start, initialize the Node Server SDK. If you are using NextJS App Router, do this in `instrumentation.ts`. You'll need to enable the [instrumentationHook](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation):
 
 ```ts
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  experimental: { instrumentationHook: true },
-};
-
-export default nextConfig;
-```
-
-2. Create a new file `instrumentation.ts` at the root of your project. This will initialize the Node Server SDK.
-
-```ts
-import { initNodeSdk } from '@/ld/server';
+import { initNodeSdk } from '@launchdarkly/react-universal-sdk/server';
 
 export async function register() {
   await initNodeSdk();
 }
 ```
 
-3. In your root layout component, render the `LDProvider` using your `LDContext` and `bootstrap`:
+2. At the application root, render the `LDProvider` with your `LDContext` and `bootstrap`. In App Router, do this in the root layout:
 
 ```tsx
 export default async function RootLayout({
@@ -91,42 +78,38 @@ export default async function RootLayout({
 }
 ```
 
-4. Server Components must use the async `useLDClientRsc` function:
+3. Server Components must use the async `useLDClientRsc` function:
 
 ```tsx
 // You should use your own getLDContext function.
 import { getLDContext } from '@/app/utils';
-import { useLDClientRsc } from '@/ld/server';
 
-export default async function Page() {
+import { useLDClientRsc } from '@launchdarkly/react-universal-sdk/server';
+
+export default async function ServerComponent() {
   const ldc = await useLDClientRsc(getLDContext());
-  const flagValue = ldc.variation('dev-test-flag');
+  const flagValue = ldc.variation('my-boolean-flag-1');
 
-  return (
-    <main className="flex min-h-screen flex-col items-center justify-between p-24">
-      Server Component: {flagValue.toString()}
-    </main>
-  );
+  return <>Server Component: {flagValue.toString()}</>;
 }
 ```
 
-5. Client Components must use the `useLDClient` hook:
+Client Components must use the `useLDClient` hook:
 
 ```tsx
 'use client';
 
-import { useLDClient } from '@/ld/client';
+import { useLDClient } from '@launchdarkly/react-universal-sdk/client';
 
-export default function LDButton() {
+export default function ClientComponent() {
   const ldc = useLDClient();
-  const flagValue = ldc.variation('dev-test-flag');
+  const flagValue = ldc.variation('my-boolean-flag-1');
 
   return <p>Client Component: {flagValue.toString()}</p>;
 }
 ```
 
-You will see both components are rendered on the server (view source on your browser). However, only Client Components
-will respond to live changes.
+You will see both Server and Client Components are rendered on the server (view source on your browser). However, only Client Components will respond to live changes because Server Components are excluded from the client bundle.
 
 ## Verifying SDK build provenance with the SLSA framework
 

packages/sdk/react-universal/example/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['plugin:@next/next/recommended'],
+};

packages/sdk/react-universal/example/.example.env.local

@@ -0,0 +1,4 @@
+# Example only - Do not commit
+
+LD_SDK_KEY='<YOUR LD SERVER SDK KEY>'
+NEXT_PUBLIC_LD_CLIENT_SIDE_ID='<YOUR LD CLIENT SDK KEY>'

packages/sdk/react-universal/example/.gitignore

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+.idea

packages/sdk/react-universal/example/README.md

@@ -1,25 +1,35 @@
-# LaunchDarkly Universal SDK example
-
 > [!IMPORTANT]  
 > This is an experimental project to demonstrate the use of LaunchDarkly with Next.js App Router.
 >
 > This is designed for the App Router. Pages router is not supported.
 
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) using App Router.
+This example app uses the LaunchDarkly React Universal SDK. It features:
 
-## Quickstart
+- Server side rendering with both Server Components and Client Components.
+- A Client Component example in [app/components/helloClientComponent.tsx](https://github.com/launchdarkly/js-core/tree/main/packages/sdk/react-universal/example/app/components/helloClientComponent.tsx)
+- A Server Component (RSC) example in [app/components/helloServerComponent.tsx](https://github.com/launchdarkly/js-core/tree/main/packages/sdk/react-universal/example/app/components/helloServerComponent.tsx)
+- Out of the box bootstrapping.
 
-To run this project:
+This is a [Next.js](https://nextjs.org/) project created with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) using App Router.
+
+## Quickstart
 
-1. Create an .env file at repo root.
-2. Add your SDK key and client-side ID:
+1. Rename `.example.env.local` to `.env.local` and use your LaunchDarkly SDK keys:
 
 ```dotenv
-LD_SDK_KEY=sdk-***
-NEXT_PUBLIC_LD_CLIENT_SIDE_ID=***
+LD_SDK_KEY='<YOUR LD SERVER SDK KEY>'
+NEXT_PUBLIC_LD_CLIENT_SIDE_ID='<YOUR LD CLIENT SDK KEY>'
 ```
 
-3. Replace `dev-test-flag` with your own flags in `app.tsx` and `LDButton.tsx`.
-4. `yarn && yarn dev`
+2. Either create `my-boolean-flag-1` in your LaunchDarkly environment or replace with your own flag in [helloClientComponent.tsx](https://github.com/launchdarkly/js-core/tree/main/packages/sdk/react-universal/example/app/components/helloClientComponent.tsx) and [helloServerComponent.tsx](https://github.com/launchdarkly/js-core/tree/main/packages/sdk/react-universal/example/app/components/helloServerComponent.tsx).
+
+3. Finally:
+
+```bash
+npm i && npm run dev
+
+# or
+yarn && yarn dev
+```
 
-You should see your flag value rendered in the browser.
+You will see both Server and Client Components are rendered on the server (view source on your browser). However, only Client Components will respond to live changes because Server Components are excluded from the client bundle.