@workos-inc/authkit-nextjs 4.0.1 → 4.1.0

package/README.md

@@ -452,14 +452,52 @@ export default function MyComponent() {
 }
 ```
 
-### Get the enabled flags for the logged in user
+### Evaluate feature flags
 
-For situations where you need access to the authenticated user's currently active feature flags, use `withAuth` to retrieve the flags from the WorkOS session.
+There are two ways to evaluate feature flags with AuthKit Next.js:
+
+- Use the `feature_flags` access token claim when you want a simple session-scoped list of enabled flags for the signed-in user.
+- Use the Feature Flags runtime client when you want server-side evaluation without storing every active flag in the user's session cookie.
+
+#### Option 1: Use the `feature_flags` claim
+
+For situations where you need access to the authenticated user's currently active feature flags and your environment includes the `feature_flags` access token claim, use `withAuth` to retrieve the flags from the WorkOS session.
 
 ```jsx
 const { featureFlags } = await withAuth();
 ```
 
+This is convenient for small flag sets because the flags are available with the user's session. Flag changes appear the next time the user logs in or the session is refreshed.
+
+#### Option 2: Use the runtime client
+
+Use the runtime client when your application has many feature flags, when the `feature_flags` claim makes the access token too large, or when you need server-side flag evaluation that stays in sync independently of the user's session. The runtime client keeps flag configuration in memory and syncs changes in the background, so create one shared instance per server process rather than one client per request.
+
+```tsx
+import { getFeatureFlagsRuntimeClient, withAuth } from '@workos-inc/authkit-nextjs';
+
+const featureFlags = getFeatureFlagsRuntimeClient();
+
+export default async function DashboardPage() {
+  const { user, organizationId } = await withAuth({ ensureSignedIn: true });
+
+  try {
+    await featureFlags.waitUntilReady({ timeoutMs: 5000 });
+  } catch (error) {
+    console.error('Feature flags client failed to initialize:', error);
+  }
+
+  const enabled = featureFlags.isEnabled('advanced-analytics', {
+    userId: user.id,
+    organizationId,
+  });
+
+  return enabled ? <AdvancedAnalytics /> : <BasicAnalytics />;
+}
+```
+
+The `getFeatureFlagsRuntimeClient` helper returns the same runtime client for every call in the current server process. Options passed to `getFeatureFlagsRuntimeClient(options)` are only used when the client is created for the first time.
+
 ### Requiring auth
 
 For pages where a signed-in user is mandatory, you can use the `ensureSignedIn` option:

package/dist/esm/feature-flags.js

@@ -0,0 +1,11 @@
+import { lazy } from './utils.js';
+import { getWorkOS } from './workos.js';
+/**
+ * Returns a shared WorkOS Feature Flags runtime client.
+ *
+ * The runtime client keeps feature flag state in sync in the background, so it
+ * should be created once per server process instead of once per request.
+ * Options are only used when the client is created for the first time.
+ */
+export const getFeatureFlagsRuntimeClient = lazy((options) => getWorkOS().featureFlags.createRuntimeClient(options));
+//# sourceMappingURL=feature-flags.js.map

package/dist/esm/feature-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flags.js","sourceRoot":"","sources":["../../src/feature-flags.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAC9C,CAAC,OAA8B,EAA6B,EAAE,CAAC,SAAS,EAAE,CAAC,YAAY,CAAC,mBAAmB,CAAC,OAAO,CAAC,CACrH,CAAC"}

package/dist/esm/index.js

@@ -5,7 +5,8 @@ import { authkit, authkitMiddleware, authkitProxy } from './middleware.js';
 export { applyResponseHeaders, handleAuthkitHeaders, handleAuthkitProxy, partitionAuthkitHeaders, isAuthkitRequestHeader, AUTHKIT_REQUEST_HEADERS, } from './middleware-helpers.js';
 import { getTokenClaims, refreshSession, saveSession, withAuth } from './session.js';
 import { validateApiKey } from './validate-api-key.js';
+import { getFeatureFlagsRuntimeClient } from './feature-flags.js';
 import { getWorkOS } from './workos.js';
 export * from './interfaces.js';
-export { AuthKitError, TokenRefreshError, authkit, authkitMiddleware, authkitProxy, getSignInUrl, getSignUpUrl, getTokenClaims, getWorkOS, handleAuth, refreshSession, saveSession, signOut, switchToOrganization, validateApiKey, withAuth, };
+export { AuthKitError, TokenRefreshError, authkit, authkitMiddleware, authkitProxy, getSignInUrl, getSignUpUrl, getFeatureFlagsRuntimeClient, getTokenClaims, getWorkOS, handleAuth, refreshSession, saveSession, signOut, switchToOrganization, validateApiKey, withAuth, };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,GAKxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,cAAc,iBAAiB,CAAC;AAEhC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,SAAS,EACT,UAAU,EACV,cAAc,EACd,WAAW,EACX,OAAO,EACP,oBAAoB,EACpB,cAAc,EACd,QAAQ,GACT,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,GAKxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,cAAc,iBAAiB,CAAC;AAEhC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,4BAA4B,EAC5B,cAAc,EACd,SAAS,EACT,UAAU,EACV,cAAc,EACd,WAAW,EACX,OAAO,EACP,oBAAoB,EACpB,cAAc,EACd,QAAQ,GACT,CAAC"}

package/dist/esm/types/feature-flags.d.ts

@@ -0,0 +1,9 @@
+import type { FeatureFlagsRuntimeClient, RuntimeClientOptions } from '@workos-inc/node';
+/**
+ * Returns a shared WorkOS Feature Flags runtime client.
+ *
+ * The runtime client keeps feature flag state in sync in the background, so it
+ * should be created once per server process instead of once per request.
+ * Options are only used when the client is created for the first time.
+ */
+export declare const getFeatureFlagsRuntimeClient: (options?: RuntimeClientOptions | undefined) => FeatureFlagsRuntimeClient;

package/dist/esm/types/index.d.ts

@@ -5,6 +5,7 @@ import { authkit, authkitMiddleware, authkitProxy } from './middleware.js';
 export { applyResponseHeaders, handleAuthkitHeaders, handleAuthkitProxy, partitionAuthkitHeaders, isAuthkitRequestHeader, AUTHKIT_REQUEST_HEADERS, type AuthkitHeadersResult, type AuthkitRedirectStatus, type AuthkitRequestHeader, type HandleAuthkitHeadersOptions, } from './middleware-helpers.js';
 import { getTokenClaims, refreshSession, saveSession, withAuth } from './session.js';
 import { validateApiKey } from './validate-api-key.js';
+import { getFeatureFlagsRuntimeClient } from './feature-flags.js';
 import { getWorkOS } from './workos.js';
 export * from './interfaces.js';
-export { AuthKitError, TokenRefreshError, authkit, authkitMiddleware, authkitProxy, getSignInUrl, getSignUpUrl, getTokenClaims, getWorkOS, handleAuth, refreshSession, saveSession, signOut, switchToOrganization, validateApiKey, withAuth, };
+export { AuthKitError, TokenRefreshError, authkit, authkitMiddleware, authkitProxy, getSignInUrl, getSignUpUrl, getFeatureFlagsRuntimeClient, getTokenClaims, getWorkOS, handleAuth, refreshSession, saveSession, signOut, switchToOrganization, validateApiKey, withAuth, };

package/dist/esm/types/utils.d.ts

@@ -17,4 +17,4 @@ export declare function errorResponseWithFallback(errorBody: {
  * @param fn - The function to be called once.
  * @returns A function that can only be called once.
  */
-export declare function lazy<T>(fn: () => T): () => T;
+export declare function lazy<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult): (...args: TArgs) => TResult;

package/dist/esm/utils.js

@@ -36,9 +36,9 @@ export function errorResponseWithFallback(errorBody) {
 export function lazy(fn) {
     let called = false;
     let result;
-    return () => {
+    return (...args) => {
         if (!called) {
-            result = fn();
+            result = fn(...args);
             called = true;
         }
         return result;

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,yDAAyD,CAAC,CAAC;IACxF,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB,EAAE,OAAiB;IACzE,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IAClE,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAExC,mEAAmE;IACnE,iCAAiC;IACjC,OAAO,YAAY,EAAE,QAAQ;QAC3B,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,CAAC;QACjD,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,SAA8D;IACtG,mEAAmE;IACnE,iCAAiC;IACjC,OAAO,YAAY,EAAE,IAAI;QACvB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC/C,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE;YACtC,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAC;AACT,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAI,EAAW;IACjC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,MAAS,CAAC;IACd,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,EAAE,EAAE,CAAC;YACd,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,yDAAyD,CAAC,CAAC;IACxF,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB,EAAE,OAAiB;IACzE,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IAClE,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAExC,mEAAmE;IACnE,iCAAiC;IACjC,OAAO,YAAY,EAAE,QAAQ;QAC3B,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,CAAC;QACjD,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,SAA8D;IACtG,mEAAmE;IACnE,iCAAiC;IACjC,OAAO,YAAY,EAAE,IAAI;QACvB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC/C,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE;YACtC,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAC;AACT,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAmC,EAA+B;IACpF,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,MAAe,CAAC;IACpB,OAAO,CAAC,GAAG,IAAW,EAAE,EAAE;QACxB,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACrB,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos-inc/authkit-nextjs",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Authentication and session helpers for using WorkOS & AuthKit with Next.js",
   "sideEffects": false,
   "type": "module",

package/src/feature-flags.spec.ts

@@ -0,0 +1,28 @@
+import { getWorkOS } from './workos.js';
+
+describe('feature flags', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.resetModules();
+  });
+
+  it('memoizes the feature flags runtime client', async () => {
+    const runtimeClient = {
+      close: vi.fn(),
+      getAllFlags: vi.fn(),
+      getFlag: vi.fn(),
+      getStats: vi.fn(),
+      isEnabled: vi.fn(),
+      waitUntilReady: vi.fn(),
+    };
+    const createRuntimeClient = vi
+      .spyOn(getWorkOS().featureFlags, 'createRuntimeClient')
+      .mockReturnValue(runtimeClient as never);
+    const { getFeatureFlagsRuntimeClient } = await import('./feature-flags.js');
+
+    expect(getFeatureFlagsRuntimeClient({ pollingIntervalMs: 5000 })).toBe(runtimeClient);
+    expect(getFeatureFlagsRuntimeClient({ pollingIntervalMs: 30000 })).toBe(runtimeClient);
+    expect(createRuntimeClient).toHaveBeenCalledTimes(1);
+    expect(createRuntimeClient).toHaveBeenCalledWith({ pollingIntervalMs: 5000 });
+  });
+});

package/src/feature-flags.ts

@@ -0,0 +1,14 @@
+import type { FeatureFlagsRuntimeClient, RuntimeClientOptions } from '@workos-inc/node';
+import { lazy } from './utils.js';
+import { getWorkOS } from './workos.js';
+
+/**
+ * Returns a shared WorkOS Feature Flags runtime client.
+ *
+ * The runtime client keeps feature flag state in sync in the background, so it
+ * should be created once per server process instead of once per request.
+ * Options are only used when the client is created for the first time.
+ */
+export const getFeatureFlagsRuntimeClient = lazy(
+  (options?: RuntimeClientOptions): FeatureFlagsRuntimeClient => getWorkOS().featureFlags.createRuntimeClient(options),
+);

package/src/index.ts

@@ -16,6 +16,7 @@ export {
 } from './middleware-helpers.js';
 import { getTokenClaims, refreshSession, saveSession, withAuth } from './session.js';
 import { validateApiKey } from './validate-api-key.js';
+import { getFeatureFlagsRuntimeClient } from './feature-flags.js';
 import { getWorkOS } from './workos.js';
 
 export * from './interfaces.js';
@@ -28,6 +29,7 @@ export {
   authkitProxy,
   getSignInUrl,
   getSignUpUrl,
+  getFeatureFlagsRuntimeClient,
   getTokenClaims,
   getWorkOS,
   handleAuth,

package/src/utils.ts

@@ -38,12 +38,12 @@ export function errorResponseWithFallback(errorBody: { error: { message: string;
  * @param fn - The function to be called once.
  * @returns A function that can only be called once.
  */
-export function lazy<T>(fn: () => T): () => T {
+export function lazy<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult): (...args: TArgs) => TResult {
   let called = false;
-  let result: T;
-  return () => {
+  let result: TResult;
+  return (...args: TArgs) => {
     if (!called) {
-      result = fn();
+      result = fn(...args);
       called = true;
     }
     return result;