@stytch/nextjs 21.4.4 → 21.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @stytch/nextjs
 
+## 21.5.0
+
+### Minor Changes
+
+- 1e9ab0e: Add a new `assumeHydrated` prop to the `StytchProvider` and `StytchB2BProvider` components. This prop allows the provider to assume whether or not the app might be hydrated in a browser environment after initially being rendered in a server environment. When `true`, the provider eagerly reads from the browser's local cache to retrieve cached session and related data. When `false`, the provider defers this initialization until after the first render, to avoid hydration errors. This prop defaults to `false` in `@stytch/nextjs`, which preserves the behavior from previous versions.
+
+  We recommend setting `assumeHydrated={false}` if your app hydrates server-rendered content on the client. Otherwise, it is safe to set `assumeHydrated={true}`. If you're unsure or notice hydration errors in your app, set `assumeHydrated={false}`.
+
+  Unless you set `assumeHydrated={true}`, you should continue to check the initialized state of the provider by checking the `isInitialized` value (returned from hooks like `useStytchUser`, `useStytchSession`, `useStytchMember`, `useStytchMemberSession`, `useStytchOrganization`, and `useStytchIsAuthorized`) or `*IsInitialized` prop (injected by HOCs like `withStytchUser`, `withStytchSession`, `withStytchMember`, `withStytchMemberSession`, and `withStytchOrganization`) before relying on any other values.
+
 ## 21.4.4
 
 ### Patch Changes

package/dist/{StytchB2BContext-a27d4ac7.d.ts → StytchB2BContext-54aa990c.d.ts}

@@ -1,15 +1,15 @@
 /// <reference types="react" />
 import React from 'react';
 import { ReactNode } from "react";
+import { PermissionsMap } from '@stytch/core/public';
 import { Member, MemberSession, Organization, StytchB2BUIClient } from '@stytch/vanilla-js/b2b';
 import { StytchB2BHeadlessClient, StytchProjectConfigurationInput } from '@stytch/vanilla-js/b2b/headless';
-import { PermissionsMap } from '@stytch/core/public';
 /**
  * The Stytch Client object passed in to <StytchB2BProvider /> in your application root.
  * Either a StytchB2BUIClient or StytchB2BHeadlessClient.
  */
 type StytchB2BClient<TProjectConfiguration extends StytchProjectConfigurationInput> = StytchB2BHeadlessClient<TProjectConfiguration> | StytchB2BUIClient<TProjectConfiguration>;
-type SWRMember = {
+type SWRMemberUninitialized = {
     /**
      * Either the active {@link Member} object, or null if the member is not logged in.
      */
@@ -22,7 +22,8 @@ type SWRMember = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWRMemberInitialized = {
     /**
      * Either the active {@link Member} object, or null if the member is not logged in.
      */
@@ -36,7 +37,8 @@ type SWRMember = {
      */
     isInitialized: true;
 };
-type SWRMemberSession = {
+type SWRMember<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRMemberInitialized : SWRMemberInitialized | SWRMemberUninitialized;
+type SWRMemberSessionUninitialized = {
     /**
      * Either the active {@link MemberSession} object, or null if the member is not logged in.
      */
@@ -49,7 +51,8 @@ type SWRMemberSession = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWRMemberSessionInitialized = {
     /**
      * Either the active {@link MemberSession} object, or null if the member is not logged in.
      */
@@ -63,7 +66,8 @@ type SWRMemberSession = {
      */
     isInitialized: true;
 };
-type SWROrganization = {
+type SWRMemberSession<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRMemberSessionInitialized : SWRMemberSessionInitialized | SWRMemberSessionUninitialized;
+type SWROrganizationUninitialized = {
     /**
      * Either the active {@link Organization} object, or null if the member is not logged in.
      */
@@ -76,7 +80,8 @@ type SWROrganization = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWROrganizationInitialized = {
     /**
      * Either the active {@link Organization} object, or null if the member is not logged in.
      */
@@ -90,6 +95,7 @@ type SWROrganization = {
      */
     isInitialized: true;
 };
+type SWROrganization<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWROrganizationInitialized : SWROrganizationInitialized | SWROrganizationUninitialized;
 declare const useIsMounted__INTERNAL: () => boolean;
 declare const isUIClient: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration>>(client: StytchB2BClient<TProjectConfiguration>) => client is StytchB2BUIClient<TProjectConfiguration>;
 /**
@@ -104,7 +110,7 @@ declare const isUIClient: <TProjectConfiguration extends Partial<import("@stytch
  * }
  * return (<h1>Welcome, {member.name}</h1>);
  */
-declare const useStytchMember: () => SWRMember;
+declare const useStytchMember: <TAssumeHydrated extends boolean = false>() => SWRMember<TAssumeHydrated>;
 /**
  * Returns the active member's Stytch member session.
  * The Stytch SDKs are used for client-side authentication and session management.
@@ -121,7 +127,7 @@ declare const useStytchMember: () => SWRMember;
  *   }
  * }, [session, isInitialized]);
  */
-declare const useStytchMemberSession: () => SWRMemberSession;
+declare const useStytchMemberSession: <TAssumeHydrated extends boolean = false>() => SWRMemberSession<TAssumeHydrated>;
 /**
  * Returns the active Stytch organization.
  * The Stytch SDKs are used for client-side authentication and session management.
@@ -134,8 +140,22 @@ declare const useStytchMemberSession: () => SWRMemberSession;
  * }
  * return (<p>Welcome to {organization.organization_name}</p>);
  */
-declare const useStytchOrganization: () => SWROrganization;
-type SWRIsAuthorized = {
+declare const useStytchOrganization: <TAssumeHydrated extends boolean = false>() => SWROrganization<TAssumeHydrated>;
+type SWRIsAuthorizedUninitialized = {
+    /**
+     * Whether the logged-in member is allowed to perform the specified action on the specified resource.
+     */
+    isAuthorized: false;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: false;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: false;
+};
+type SWRIsAuthorizedInitialized = {
     /**
      * Whether the logged-in member is allowed to perform the specified action on the specified resource.
      */
@@ -149,6 +169,7 @@ type SWRIsAuthorized = {
      */
     isInitialized: boolean;
 };
+type SWRIsAuthorized<TAlwaysInitialized extends boolean> = TAlwaysInitialized extends true ? SWRIsAuthorizedInitialized : SWRIsAuthorizedInitialized | SWRIsAuthorizedUninitialized;
 /**
  * Determines whether the logged-in member is allowed to perform the specified action on the specified resource.
  * Returns `true` if the member can perform the action, `false` otherwise.
@@ -158,10 +179,10 @@ type SWRIsAuthorized = {
  *
  * Remember - authorization checks for sensitive actions should always occur on the backend as well.
  * @example
- * const isAuthorized = useStytchIsAuthorized<Permissions>('documents', 'edit');
+ * const { isAuthorized } = useStytchIsAuthorized<Permissions>('documents', 'edit');
  * return <button disabled={!isAuthorized}>Edit</button>
  */
-declare const useStytchIsAuthorized: (resourceId: string, action: string) => SWRIsAuthorized;
+declare const useStytchIsAuthorized: <TAssumeHydrated extends boolean = false>(resourceId: string, action: string) => SWRIsAuthorized<TAssumeHydrated>;
 /**
  * Returns the Stytch B2B client stored in the Stytch context.
  *
@@ -175,17 +196,17 @@ declare const useStytchB2BClient: <TProjectConfiguration extends Partial<import(
 declare const withStytchB2BClient: <T extends object, TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration>>(Component: React.ComponentType<T & {
     stytch: StytchB2BHeadlessClient<TProjectConfiguration>;
 }>) => React.ComponentType<T>;
-declare const withStytchMember: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchMember: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchMember: Member | null;
     stytchMemberIsInitialized: boolean;
     stytchMemberIsFromCache: boolean;
 }>) => React.ComponentType<T>;
-declare const withStytchMemberSession: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchMemberSession: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchMemberSession: MemberSession | null;
     stytchMemberSessionIsInitialized: boolean;
     stytchMemberSessionIsFromCache: boolean;
 }>) => React.ComponentType<T>;
-declare const withStytchOrganization: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchOrganization: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchOrganization: Organization | null;
     stytchOrganizationIsInitialized: boolean;
     stytchOrganizationIsFromCache: boolean;
@@ -219,6 +240,20 @@ interface StytchB2BProviderProps<TProjectConfiguration extends StytchProjectConf
      * A Stytch client instance, created using either {@link createStytchHeadlessClient} or {@link createStytchUIClient}
      */
     stytch: StytchB2BClient<TProjectConfiguration>;
+    /**
+     * When true, the provider will assume that the component will only be
+     * rendered in a browser environment, either in a single-page application or
+     * after completing hydration of a server-rendered application. This allows
+     * cached values to be retrieved from the browser on the first render, meaning
+     * that the `isInitialized` value returned from Stytch hooks will be `true`
+     * starting from the first render.
+     *
+     * When `false`, the provider will defer initialization until after the first
+     * render, and `isInitialized` will initially be `false`.
+     *
+     * This value defaults to `false` in `@stytch/nextjs`.
+     */
+    assumeHydrated?: boolean;
     children?: ReactNode;
 }
 /**
@@ -233,5 +268,5 @@ interface StytchB2BProviderProps<TProjectConfiguration extends StytchProjectConf
  *   </StytchB2BProvider>
  * )
  */
-declare const StytchB2BProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children, }: StytchB2BProviderProps<TProjectConfiguration>) => JSX.Element;
+declare const StytchB2BProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children, assumeHydrated, }: StytchB2BProviderProps<TProjectConfiguration>) => JSX.Element;
 export { useIsMounted__INTERNAL, isUIClient, useStytchMember, useStytchMemberSession, useStytchOrganization, useStytchIsAuthorized, useStytchB2BClient, withStytchB2BClient, withStytchMember, withStytchMemberSession, withStytchOrganization, withStytchPermissions, StytchB2BProviderProps, StytchB2BProvider };

package/dist/{StytchB2BContext-c11ed503.js → StytchB2BContext-54aa990c.js}

@@ -1,6 +1,6 @@
-import React, { createContext, useContext, useEffect, useMemo } from 'react';
+import React, { createContext, useContext, useEffect, useMemo, useCallback, useRef } from 'react';
 import { i as invariant, u as useAsyncState, m as mergeWithStableProps } from './useIsomorphicLayoutEffect-1babb81e.js';
-import { i as isStytchSSRProxy, n as noProviderError } from './StytchSSRProxy-4e34fb34.js';
+import { i as isStytchSSRProxy, n as noProviderError } from './StytchSSRProxy-34c789b5.js';
 
 const initialMember = {
     member: null,
@@ -86,7 +86,7 @@ const useStytchOrganization = () => {
  *
  * Remember - authorization checks for sensitive actions should always occur on the backend as well.
  * @example
- * const isAuthorized = useStytchIsAuthorized<Permissions>('documents', 'edit');
+ * const { isAuthorized } = useStytchIsAuthorized<Permissions>('documents', 'edit');
  * return <button disabled={!isAuthorized}>Edit</button>
  */
 const useStytchIsAuthorized = (resourceId, action) => {
@@ -219,33 +219,40 @@ const withStytchPermissions = (Component) => {
  *   </StytchB2BProvider>
  * )
  */
-const StytchB2BProvider = ({ stytch, children, }) => {
+const StytchB2BProvider = ({ stytch, children, assumeHydrated = false, }) => {
+    invariant(!useIsMounted__INTERNAL(), 'You cannot render a <StytchB2BProvider> inside another <StytchB2BProvider>.');
+    invariant(!assumeHydrated || typeof window !== 'undefined', 'The `assumeHydrated` prop must be set to `false` when using StytchB2BProvider in a server environment.');
     const ctx = useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
-    const [{ member, session, organization }, setClientState] = useAsyncState({
-        member: initialMember,
-        session: initialMemberSession,
-        organization: initialOrganization,
-    });
+    const getHydratedState = useCallback(() => {
+        return {
+            member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
+            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
+            organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
+        };
+    }, [stytch]);
+    const getInitialState = () => {
+        return {
+            member: initialMember,
+            session: initialMemberSession,
+            organization: initialOrganization,
+        };
+    };
+    const [{ member, session, organization }, setClientState] = useAsyncState(() => assumeHydrated ? getHydratedState() : getInitialState());
+    // Store the initial value of `assumeHydrated` in a ref, because it is
+    // logically only relevant for the first render
+    const assumeHydratedRef = useRef(assumeHydrated);
     useEffect(() => {
         if (isStytchSSRProxy(stytch)) {
             return;
         }
-        setClientState({
-            member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
-            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-            organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
-        });
-        return stytch.onStateChange(() => {
-            setClientState((oldState) => {
-                const newState = {
-                    member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
-                    session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-                    organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
-                };
-                return mergeWithStableProps(oldState, newState);
-            });
-        });
-    }, [setClientState, stytch]);
+        const updateState = () => {
+            setClientState((oldState) => mergeWithStableProps(oldState, getHydratedState()));
+        };
+        if (!assumeHydratedRef.current) {
+            updateState();
+        }
+        return stytch.onStateChange(updateState);
+    }, [getHydratedState, setClientState, stytch]);
     return (React.createElement(StytchB2BContext.Provider, { value: ctx },
         React.createElement(StytchOrganizationContext.Provider, { value: organization },
             React.createElement(StytchMemberContext.Provider, { value: member },

package/dist/{StytchB2BContext-c11ed503.d.ts → StytchB2BContext-c5062f9b.d.ts}

@@ -1,15 +1,15 @@
 /// <reference types="react" />
 import React from 'react';
 import { ReactNode } from "react";
+import { PermissionsMap } from '@stytch/core/public';
 import { Member, MemberSession, Organization, StytchB2BUIClient } from '@stytch/vanilla-js/b2b';
 import { StytchB2BHeadlessClient, StytchProjectConfigurationInput } from '@stytch/vanilla-js/b2b/headless';
-import { PermissionsMap } from '@stytch/core/public';
 /**
  * The Stytch Client object passed in to <StytchB2BProvider /> in your application root.
  * Either a StytchB2BUIClient or StytchB2BHeadlessClient.
  */
 type StytchB2BClient<TProjectConfiguration extends StytchProjectConfigurationInput> = StytchB2BHeadlessClient<TProjectConfiguration> | StytchB2BUIClient<TProjectConfiguration>;
-type SWRMember = {
+type SWRMemberUninitialized = {
     /**
      * Either the active {@link Member} object, or null if the member is not logged in.
      */
@@ -22,7 +22,8 @@ type SWRMember = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWRMemberInitialized = {
     /**
      * Either the active {@link Member} object, or null if the member is not logged in.
      */
@@ -36,7 +37,8 @@ type SWRMember = {
      */
     isInitialized: true;
 };
-type SWRMemberSession = {
+type SWRMember<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRMemberInitialized : SWRMemberInitialized | SWRMemberUninitialized;
+type SWRMemberSessionUninitialized = {
     /**
      * Either the active {@link MemberSession} object, or null if the member is not logged in.
      */
@@ -49,7 +51,8 @@ type SWRMemberSession = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWRMemberSessionInitialized = {
     /**
      * Either the active {@link MemberSession} object, or null if the member is not logged in.
      */
@@ -63,7 +66,8 @@ type SWRMemberSession = {
      */
     isInitialized: true;
 };
-type SWROrganization = {
+type SWRMemberSession<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRMemberSessionInitialized : SWRMemberSessionInitialized | SWRMemberSessionUninitialized;
+type SWROrganizationUninitialized = {
     /**
      * Either the active {@link Organization} object, or null if the member is not logged in.
      */
@@ -76,7 +80,8 @@ type SWROrganization = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWROrganizationInitialized = {
     /**
      * Either the active {@link Organization} object, or null if the member is not logged in.
      */
@@ -90,6 +95,7 @@ type SWROrganization = {
      */
     isInitialized: true;
 };
+type SWROrganization<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWROrganizationInitialized : SWROrganizationInitialized | SWROrganizationUninitialized;
 declare const useIsMounted__INTERNAL: () => boolean;
 declare const isUIClient: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration>>(client: StytchB2BClient<TProjectConfiguration>) => client is StytchB2BUIClient<TProjectConfiguration>;
 /**
@@ -104,7 +110,7 @@ declare const isUIClient: <TProjectConfiguration extends Partial<import("@stytch
  * }
  * return (<h1>Welcome, {member.name}</h1>);
  */
-declare const useStytchMember: () => SWRMember;
+declare const useStytchMember: <TAssumeHydrated extends boolean = false>() => SWRMember<TAssumeHydrated>;
 /**
  * Returns the active member's Stytch member session.
  * The Stytch SDKs are used for client-side authentication and session management.
@@ -121,7 +127,7 @@ declare const useStytchMember: () => SWRMember;
  *   }
  * }, [session, isInitialized]);
  */
-declare const useStytchMemberSession: () => SWRMemberSession;
+declare const useStytchMemberSession: <TAssumeHydrated extends boolean = false>() => SWRMemberSession<TAssumeHydrated>;
 /**
  * Returns the active Stytch organization.
  * The Stytch SDKs are used for client-side authentication and session management.
@@ -134,8 +140,22 @@ declare const useStytchMemberSession: () => SWRMemberSession;
  * }
  * return (<p>Welcome to {organization.organization_name}</p>);
  */
-declare const useStytchOrganization: () => SWROrganization;
-type SWRIsAuthorized = {
+declare const useStytchOrganization: <TAssumeHydrated extends boolean = false>() => SWROrganization<TAssumeHydrated>;
+type SWRIsAuthorizedUninitialized = {
+    /**
+     * Whether the logged-in member is allowed to perform the specified action on the specified resource.
+     */
+    isAuthorized: false;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: false;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: false;
+};
+type SWRIsAuthorizedInitialized = {
     /**
      * Whether the logged-in member is allowed to perform the specified action on the specified resource.
      */
@@ -149,6 +169,7 @@ type SWRIsAuthorized = {
      */
     isInitialized: boolean;
 };
+type SWRIsAuthorized<TAlwaysInitialized extends boolean> = TAlwaysInitialized extends true ? SWRIsAuthorizedInitialized : SWRIsAuthorizedInitialized | SWRIsAuthorizedUninitialized;
 /**
  * Determines whether the logged-in member is allowed to perform the specified action on the specified resource.
  * Returns `true` if the member can perform the action, `false` otherwise.
@@ -158,10 +179,10 @@ type SWRIsAuthorized = {
  *
  * Remember - authorization checks for sensitive actions should always occur on the backend as well.
  * @example
- * const isAuthorized = useStytchIsAuthorized<Permissions>('documents', 'edit');
+ * const { isAuthorized } = useStytchIsAuthorized<Permissions>('documents', 'edit');
  * return <button disabled={!isAuthorized}>Edit</button>
  */
-declare const useStytchIsAuthorized: (resourceId: string, action: string) => SWRIsAuthorized;
+declare const useStytchIsAuthorized: <TAssumeHydrated extends boolean = false>(resourceId: string, action: string) => SWRIsAuthorized<TAssumeHydrated>;
 /**
  * Returns the Stytch B2B client stored in the Stytch context.
  *
@@ -175,17 +196,17 @@ declare const useStytchB2BClient: <TProjectConfiguration extends Partial<import(
 declare const withStytchB2BClient: <T extends object, TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration>>(Component: React.ComponentType<T & {
     stytch: StytchB2BHeadlessClient<TProjectConfiguration>;
 }>) => React.ComponentType<T>;
-declare const withStytchMember: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchMember: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchMember: Member | null;
     stytchMemberIsInitialized: boolean;
     stytchMemberIsFromCache: boolean;
 }>) => React.ComponentType<T>;
-declare const withStytchMemberSession: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchMemberSession: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchMemberSession: MemberSession | null;
     stytchMemberSessionIsInitialized: boolean;
     stytchMemberSessionIsFromCache: boolean;
 }>) => React.ComponentType<T>;
-declare const withStytchOrganization: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchOrganization: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchOrganization: Organization | null;
     stytchOrganizationIsInitialized: boolean;
     stytchOrganizationIsFromCache: boolean;
@@ -219,6 +240,20 @@ interface StytchB2BProviderProps<TProjectConfiguration extends StytchProjectConf
      * A Stytch client instance, created using either {@link createStytchHeadlessClient} or {@link createStytchUIClient}
      */
     stytch: StytchB2BClient<TProjectConfiguration>;
+    /**
+     * When true, the provider will assume that the component will only be
+     * rendered in a browser environment, either in a single-page application or
+     * after completing hydration of a server-rendered application. This allows
+     * cached values to be retrieved from the browser on the first render, meaning
+     * that the `isInitialized` value returned from Stytch hooks will be `true`
+     * starting from the first render.
+     *
+     * When `false`, the provider will defer initialization until after the first
+     * render, and `isInitialized` will initially be `false`.
+     *
+     * This value defaults to `false` in `@stytch/nextjs`.
+     */
+    assumeHydrated?: boolean;
     children?: ReactNode;
 }
 /**
@@ -233,5 +268,5 @@ interface StytchB2BProviderProps<TProjectConfiguration extends StytchProjectConf
  *   </StytchB2BProvider>
  * )
  */
-declare const StytchB2BProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children, }: StytchB2BProviderProps<TProjectConfiguration>) => JSX.Element;
+declare const StytchB2BProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children, assumeHydrated, }: StytchB2BProviderProps<TProjectConfiguration>) => JSX.Element;
 export { useIsMounted__INTERNAL, isUIClient, useStytchMember, useStytchMemberSession, useStytchOrganization, useStytchIsAuthorized, useStytchB2BClient, withStytchB2BClient, withStytchMember, withStytchMemberSession, withStytchOrganization, withStytchPermissions, StytchB2BProviderProps, StytchB2BProvider };

package/dist/{StytchB2BContext-a27d4ac7.js → StytchB2BContext-c5062f9b.js}

@@ -2,7 +2,7 @@
 
 var React = require('react');
 var useIsomorphicLayoutEffect = require('./useIsomorphicLayoutEffect-65746ef3.js');
-var StytchSSRProxy = require('./StytchSSRProxy-c9d3bc41.js');
+var StytchSSRProxy = require('./StytchSSRProxy-86bc42b3.js');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -92,7 +92,7 @@ const useStytchOrganization = () => {
  *
  * Remember - authorization checks for sensitive actions should always occur on the backend as well.
  * @example
- * const isAuthorized = useStytchIsAuthorized<Permissions>('documents', 'edit');
+ * const { isAuthorized } = useStytchIsAuthorized<Permissions>('documents', 'edit');
  * return <button disabled={!isAuthorized}>Edit</button>
  */
 const useStytchIsAuthorized = (resourceId, action) => {
@@ -225,33 +225,40 @@ const withStytchPermissions = (Component) => {
  *   </StytchB2BProvider>
  * )
  */
-const StytchB2BProvider = ({ stytch, children, }) => {
+const StytchB2BProvider = ({ stytch, children, assumeHydrated = false, }) => {
+    useIsomorphicLayoutEffect.invariant(!useIsMounted__INTERNAL(), 'You cannot render a <StytchB2BProvider> inside another <StytchB2BProvider>.');
+    useIsomorphicLayoutEffect.invariant(!assumeHydrated || typeof window !== 'undefined', 'The `assumeHydrated` prop must be set to `false` when using StytchB2BProvider in a server environment.');
     const ctx = React.useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
-    const [{ member, session, organization }, setClientState] = useIsomorphicLayoutEffect.useAsyncState({
-        member: initialMember,
-        session: initialMemberSession,
-        organization: initialOrganization,
-    });
+    const getHydratedState = React.useCallback(() => {
+        return {
+            member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
+            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
+            organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
+        };
+    }, [stytch]);
+    const getInitialState = () => {
+        return {
+            member: initialMember,
+            session: initialMemberSession,
+            organization: initialOrganization,
+        };
+    };
+    const [{ member, session, organization }, setClientState] = useIsomorphicLayoutEffect.useAsyncState(() => assumeHydrated ? getHydratedState() : getInitialState());
+    // Store the initial value of `assumeHydrated` in a ref, because it is
+    // logically only relevant for the first render
+    const assumeHydratedRef = React.useRef(assumeHydrated);
     React.useEffect(() => {
         if (StytchSSRProxy.isStytchSSRProxy(stytch)) {
             return;
         }
-        setClientState({
-            member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
-            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-            organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
-        });
-        return stytch.onStateChange(() => {
-            setClientState((oldState) => {
-                const newState = {
-                    member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
-                    session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-                    organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
-                };
-                return useIsomorphicLayoutEffect.mergeWithStableProps(oldState, newState);
-            });
-        });
-    }, [setClientState, stytch]);
+        const updateState = () => {
+            setClientState((oldState) => useIsomorphicLayoutEffect.mergeWithStableProps(oldState, getHydratedState()));
+        };
+        if (!assumeHydratedRef.current) {
+            updateState();
+        }
+        return stytch.onStateChange(updateState);
+    }, [getHydratedState, setClientState, stytch]);
     return (React__default["default"].createElement(StytchB2BContext.Provider, { value: ctx },
         React__default["default"].createElement(StytchOrganizationContext.Provider, { value: organization },
             React__default["default"].createElement(StytchMemberContext.Provider, { value: member },

package/dist/{StytchSSRProxy-4e34fb34.js → StytchSSRProxy-34c789b5.js}

@@ -1,7 +1,8 @@
 const noProviderError = (item, provider = 'StytchProvider') => `${item} can only be used inside <${provider}>.`;
+const providerMustBeUniqueError = 'You cannot render a <StytchProvider> inside another <StytchProvider>.';
 const noHeadlessClientError = `Tried to create a Stytch Login UI element using the Stytch Headless SDK.
 You must use the UI SDK to use UI elements.
-Please make sure you are importing createStytchHeadlessClient from @stytch/nextjs/ui and not from @stytch/nextjs/headless.`;
+Please make sure you are using a Stytch UI client, not a Stytch Headless client.`;
 const cannotInvokeMethodOnServerError = (path) => `[Stytch] Invalid serverside function call to ${path}.
 The Stytch Javascript SDK is intended to ony be used on the client side.
 Make sure to wrap your API calls in a hook to ensure they are executed on the client.
@@ -44,4 +45,4 @@ const createProxy = (path) => {
 };
 const createStytchSSRProxy = () => createProxy('stytch');
 
-export { noHeadlessClientError as a, createStytchSSRProxy as c, isStytchSSRProxy as i, noProviderError as n };
+export { noHeadlessClientError as a, createStytchSSRProxy as c, isStytchSSRProxy as i, noProviderError as n, providerMustBeUniqueError as p };

package/dist/{StytchSSRProxy-c9d3bc41.js → StytchSSRProxy-86bc42b3.js}

@@ -1,9 +1,10 @@
 'use strict';
 
 const noProviderError = (item, provider = 'StytchProvider') => `${item} can only be used inside <${provider}>.`;
+const providerMustBeUniqueError = 'You cannot render a <StytchProvider> inside another <StytchProvider>.';
 const noHeadlessClientError = `Tried to create a Stytch Login UI element using the Stytch Headless SDK.
 You must use the UI SDK to use UI elements.
-Please make sure you are importing createStytchHeadlessClient from @stytch/nextjs/ui and not from @stytch/nextjs/headless.`;
+Please make sure you are using a Stytch UI client, not a Stytch Headless client.`;
 const cannotInvokeMethodOnServerError = (path) => `[Stytch] Invalid serverside function call to ${path}.
 The Stytch Javascript SDK is intended to ony be used on the client side.
 Make sure to wrap your API calls in a hook to ensure they are executed on the client.
@@ -50,3 +51,4 @@ exports.createStytchSSRProxy = createStytchSSRProxy;
 exports.isStytchSSRProxy = isStytchSSRProxy;
 exports.noHeadlessClientError = noHeadlessClientError;
 exports.noProviderError = noProviderError;
+exports.providerMustBeUniqueError = providerMustBeUniqueError;

package/dist/adminPortal/index.esm.js

@@ -1,8 +1,8 @@
 import { mountAdminPortalSSO, mountAdminPortalOrgSettings, mountAdminPortalMemberManagement, mountAdminPortalSCIM } from '@stytch/vanilla-js/b2b/adminPortal';
 export { AdminPortalB2BProducts } from '@stytch/vanilla-js/b2b/adminPortal';
 import React, { useRef } from 'react';
-import { u as useIsMounted__INTERNAL, a as useStytchB2BClient } from '../StytchB2BContext-c11ed503.js';
-import { n as noProviderError } from '../StytchSSRProxy-4e34fb34.js';
+import { u as useIsMounted__INTERNAL, a as useStytchB2BClient } from '../StytchB2BContext-54aa990c.js';
+import { n as noProviderError } from '../StytchSSRProxy-34c789b5.js';
 import { i as invariant, a as useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect-1babb81e.js';
 
 const makeAdminPortalComponent = (mountFn, componentName) => {

package/dist/adminPortal/index.js

@@ -4,8 +4,8 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var adminPortal = require('@stytch/vanilla-js/b2b/adminPortal');
 var React = require('react');
-var StytchB2BContext = require('../StytchB2BContext-a27d4ac7.js');
-var StytchSSRProxy = require('../StytchSSRProxy-c9d3bc41.js');
+var StytchB2BContext = require('../StytchB2BContext-c5062f9b.js');
+var StytchSSRProxy = require('../StytchSSRProxy-86bc42b3.js');
 var useIsomorphicLayoutEffect = require('../useIsomorphicLayoutEffect-65746ef3.js');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }

package/dist/b2b/index.d.ts

@@ -141,6 +141,6 @@ declare const StytchB2B: <TProjectConfiguration extends Partial<import("@stytch/
  * />
  */
 declare const B2BIdentityProvider: ({ styles, callbacks, getIDPConsentManifest }: B2BIdentityProviderProps) => React.JSX.Element;
-export { StytchB2BProvider, useStytchB2BClient, useStytchMemberSession, useStytchMember, useStytchIsAuthorized, useStytchOrganization, withStytchB2BClient, withStytchMemberSession, withStytchMember, withStytchOrganization, withStytchPermissions } from "../StytchB2BContext-a27d4ac7.js";
+export { StytchB2BProvider, useStytchB2BClient, useStytchMemberSession, useStytchMember, useStytchIsAuthorized, useStytchOrganization, withStytchB2BClient, withStytchMemberSession, withStytchMember, withStytchOrganization, withStytchPermissions } from "../StytchB2BContext-c5062f9b.js";
 export { StytchB2B, B2BIdentityProvider };
-export type { StytchB2BProviderProps } from "../StytchB2BContext-a27d4ac7.js";
+export type { StytchB2BProviderProps } from "../StytchB2BContext-c5062f9b.js";

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

@@ -141,6 +141,6 @@ declare const StytchB2B: <TProjectConfiguration extends Partial<import("@stytch/
  * />
  */
 declare const B2BIdentityProvider: ({ styles, callbacks, getIDPConsentManifest }: B2BIdentityProviderProps) => React.JSX.Element;
-export { StytchB2BProvider, useStytchB2BClient, useStytchMemberSession, useStytchMember, useStytchIsAuthorized, useStytchOrganization, withStytchB2BClient, withStytchMemberSession, withStytchMember, withStytchOrganization, withStytchPermissions } from "../StytchB2BContext-c11ed503.js";
+export { StytchB2BProvider, useStytchB2BClient, useStytchMemberSession, useStytchMember, useStytchIsAuthorized, useStytchOrganization, withStytchB2BClient, withStytchMemberSession, withStytchMember, withStytchOrganization, withStytchPermissions } from "../StytchB2BContext-54aa990c.js";
 export { StytchB2B, B2BIdentityProvider };
-export type { StytchB2BProviderProps } from "../StytchB2BContext-c11ed503.js";
+export type { StytchB2BProviderProps } from "../StytchB2BContext-54aa990c.js";

package/dist/b2b/index.esm.js

@@ -1,8 +1,8 @@
-import { u as useIsMounted__INTERNAL, a as useStytchB2BClient, i as isUIClient, b as useStytchMember } from '../StytchB2BContext-c11ed503.js';
-export { S as StytchB2BProvider, a as useStytchB2BClient, d as useStytchIsAuthorized, b as useStytchMember, c as useStytchMemberSession, e as useStytchOrganization, w as withStytchB2BClient, g as withStytchMember, f as withStytchMemberSession, h as withStytchOrganization, j as withStytchPermissions } from '../StytchB2BContext-c11ed503.js';
+import { u as useIsMounted__INTERNAL, a as useStytchB2BClient, i as isUIClient, b as useStytchMember } from '../StytchB2BContext-54aa990c.js';
+export { S as StytchB2BProvider, a as useStytchB2BClient, d as useStytchIsAuthorized, b as useStytchMember, c as useStytchMemberSession, e as useStytchOrganization, w as withStytchB2BClient, g as withStytchMember, f as withStytchMemberSession, h as withStytchOrganization, j as withStytchPermissions } from '../StytchB2BContext-54aa990c.js';
 import React, { useRef } from 'react';
 import { i as invariant, a as useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect-1babb81e.js';
-import { a as noHeadlessClientError, n as noProviderError } from '../StytchSSRProxy-4e34fb34.js';
+import { a as noHeadlessClientError, n as noProviderError } from '../StytchSSRProxy-34c789b5.js';
 
 /**
  * The Stytch B2B UI component.

package/dist/b2b/index.headless.esm.js

@@ -1,5 +1,5 @@
 import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
-import { c as createStytchSSRProxy } from '../StytchSSRProxy-4e34fb34.js';
+import { c as createStytchSSRProxy } from '../StytchSSRProxy-34c789b5.js';
 
 /**
  * Creates a Headless Stytch client object to call the stytch B2B APIs.

package/dist/b2b/index.headless.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var headless = require('@stytch/vanilla-js/b2b/headless');
-var StytchSSRProxy = require('../StytchSSRProxy-c9d3bc41.js');
+var StytchSSRProxy = require('../StytchSSRProxy-86bc42b3.js');
 
 /**
  * Creates a Headless Stytch client object to call the stytch B2B APIs.

package/dist/b2b/index.js

@@ -2,10 +2,10 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var StytchB2BContext = require('../StytchB2BContext-a27d4ac7.js');
+var StytchB2BContext = require('../StytchB2BContext-c5062f9b.js');
 var React = require('react');
 var useIsomorphicLayoutEffect = require('../useIsomorphicLayoutEffect-65746ef3.js');
-var StytchSSRProxy = require('../StytchSSRProxy-c9d3bc41.js');
+var StytchSSRProxy = require('../StytchSSRProxy-86bc42b3.js');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 

package/dist/b2b/index.ui.esm.js

@@ -1,5 +1,5 @@
 import { StytchB2BUIClient } from '@stytch/vanilla-js/b2b';
-import { c as createStytchSSRProxy } from '../StytchSSRProxy-4e34fb34.js';
+import { c as createStytchSSRProxy } from '../StytchSSRProxy-34c789b5.js';
 
 /**
  * Creates a Stytch UI client object to call the Stytch APIs and render Stytch UI components.

package/dist/b2b/index.ui.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var b2b = require('@stytch/vanilla-js/b2b');
-var StytchSSRProxy = require('../StytchSSRProxy-c9d3bc41.js');
+var StytchSSRProxy = require('../StytchSSRProxy-86bc42b3.js');
 
 /**
  * Creates a Stytch UI client object to call the Stytch APIs and render Stytch UI components.

package/dist/errors-d9d5fbc8.d.ts

@@ -0,0 +1,5 @@
+declare const noProviderError: (item: string, provider?: string) => string;
+declare const providerMustBeUniqueError = "You cannot render a <StytchProvider> inside another <StytchProvider>.";
+declare const noHeadlessClientError = "Tried to create a Stytch Login UI element using the Stytch Headless SDK.\nYou must use the UI SDK to use UI elements.\nPlease make sure you are using a Stytch UI client, not a Stytch Headless client.";
+declare const cannotInvokeMethodOnServerError: (path: string) => string;
+export { noProviderError, providerMustBeUniqueError, noHeadlessClientError, cannotInvokeMethodOnServerError };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { StytchHeadlessClient } from "@stytch/vanilla-js/headless";
  * Either a StytchUIClient or StytchHeadlessClient.
  */
 type StytchClient<TProjectConfiguration extends StytchProjectConfigurationInput> = StytchUIClient<TProjectConfiguration> | StytchHeadlessClient<TProjectConfiguration>;
-type SWRUser = {
+type SWRUserUninitialized = {
     /**
      * Either the active {@link User} object, or null if the user is not logged in.
      */
@@ -21,7 +21,8 @@ type SWRUser = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWRUserInitialized = {
     /**
      * Either the active {@link User} object, or null if the user is not logged in.
      */
@@ -35,7 +36,8 @@ type SWRUser = {
      */
     isInitialized: true;
 };
-type SWRSession = {
+type SWRUser<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRUserInitialized : SWRUserInitialized | SWRUserUninitialized;
+type SWRSessionUninitialized = {
     /**
      * Either the active {@link Session} object, or null if the user is not logged in.
      */
@@ -48,7 +50,8 @@ type SWRSession = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWRSessionInitialized = {
     /**
      * Either the active {@link Session} object, or null if the user is not logged in.
      */
@@ -62,6 +65,7 @@ type SWRSession = {
      */
     isInitialized: true;
 };
+type SWRSession<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRSessionInitialized : SWRSessionInitialized | SWRSessionUninitialized;
 /**
  * Returns the active User.
  * The Stytch SDKs are used for client-side authentication and session management.
@@ -74,7 +78,7 @@ type SWRSession = {
  * }
  * return (<h1>Welcome, {user.name.first_name}</h1>);
  */
-declare const useStytchUser: () => SWRUser;
+declare const useStytchUser: <TAssumeHydrated extends boolean = false>() => SWRUser<TAssumeHydrated>;
 /**
  * Returns the active user's Stytch session.
  * The Stytch SDKs are used for client-side authentication and session management.
@@ -91,7 +95,7 @@ declare const useStytchUser: () => SWRUser;
  *   }
  * }, [session, isInitialized]);
  */
-declare const useStytchSession: () => SWRSession;
+declare const useStytchSession: <TAssumeHydrated extends boolean = false>() => SWRSession<TAssumeHydrated>;
 /**
  * Returns the Stytch client stored in the Stytch context.
  *
@@ -105,12 +109,12 @@ declare const useStytch: <TProjectConfiguration extends Partial<import("@stytch/
 declare const withStytch: <T extends object, TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>(Component: React.ComponentType<T & {
     stytch: StytchClient<TProjectConfiguration>;
 }>) => React.ComponentType<T>;
-declare const withStytchUser: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchUser: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchUser: User | null;
     stytchUserIsInitialized: boolean;
     stytchUserIsFromCache: boolean;
 }>) => React.ComponentType<T>;
-declare const withStytchSession: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchSession: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchSession: Session | null;
     stytchSessionIsInitialized: boolean;
     stytchSessionIsFromCache: boolean;
@@ -120,6 +124,20 @@ interface StytchProviderProps<TProjectConfiguration extends StytchProjectConfigu
      * A Stytch client instance, created using either {@link createStytchHeadlessClient} or {@link createStytchUIClient}
      */
     stytch: StytchClient<TProjectConfiguration>;
+    /**
+     * When true, the provider will assume that the component will only be
+     * rendered in a browser environment, either in a single-page application or
+     * after completing hydration of a server-rendered application. This allows
+     * cached values to be retrieved from the browser on the first render, meaning
+     * that the `isInitialized` value returned from Stytch hooks will be `true`
+     * starting from the first render.
+     *
+     * When `false`, the provider will defer initialization until after the first
+     * render, and `isInitialized` will initially be `false`.
+     *
+     * This value defaults to `false` in `@stytch/nextjs`.
+     */
+    assumeHydrated?: boolean;
     children?: ReactNode;
 }
 /**
@@ -134,7 +152,7 @@ interface StytchProviderProps<TProjectConfiguration extends StytchProjectConfigu
  *   </StytchProvider>
  * )
  */
-declare const StytchProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children }: StytchProviderProps<TProjectConfiguration>) => JSX.Element;
+declare const StytchProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children, assumeHydrated }: StytchProviderProps<TProjectConfiguration>) => JSX.Element;
 interface StytchProps<TProjectConfiguration extends StytchProjectConfigurationInput = Stytch.DefaultProjectConfiguration> {
     /**
      * A {@link StytchLoginConfig} object. Add products and product-specific config to this object to change the login methods shown.
@@ -321,5 +339,5 @@ declare const StytchPasskeyRegistration: <TProjectConfiguration extends Partial<
  * />
  */
 declare const IdentityProvider: ({ styles, callbacks }: IdentityProviderProps) => React.JSX.Element;
-export { StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser, StytchLogin, StytchPasswordReset, StytchPasskeyRegistration, IdentityProvider };
-export type { StytchProviderProps };
+export { IdentityProvider, StytchLogin, StytchPasskeyRegistration, StytchPasswordReset, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };
+export type { StytchProviderProps, IdentityProviderProps, StytchProps, StytchResetPasswordProps };

package/dist/index.esm.d.ts

@@ -8,7 +8,7 @@ import { StytchHeadlessClient } from "@stytch/vanilla-js/headless";
  * Either a StytchUIClient or StytchHeadlessClient.
  */
 type StytchClient<TProjectConfiguration extends StytchProjectConfigurationInput> = StytchUIClient<TProjectConfiguration> | StytchHeadlessClient<TProjectConfiguration>;
-type SWRUser = {
+type SWRUserUninitialized = {
     /**
      * Either the active {@link User} object, or null if the user is not logged in.
      */
@@ -21,7 +21,8 @@ type SWRUser = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWRUserInitialized = {
     /**
      * Either the active {@link User} object, or null if the user is not logged in.
      */
@@ -35,7 +36,8 @@ type SWRUser = {
      */
     isInitialized: true;
 };
-type SWRSession = {
+type SWRUser<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRUserInitialized : SWRUserInitialized | SWRUserUninitialized;
+type SWRSessionUninitialized = {
     /**
      * Either the active {@link Session} object, or null if the user is not logged in.
      */
@@ -48,7 +50,8 @@ type SWRSession = {
      * If true, indicates that the SDK has completed initialization.
      */
     isInitialized: false;
-} | {
+};
+type SWRSessionInitialized = {
     /**
      * Either the active {@link Session} object, or null if the user is not logged in.
      */
@@ -62,6 +65,7 @@ type SWRSession = {
      */
     isInitialized: true;
 };
+type SWRSession<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRSessionInitialized : SWRSessionInitialized | SWRSessionUninitialized;
 /**
  * Returns the active User.
  * The Stytch SDKs are used for client-side authentication and session management.
@@ -74,7 +78,7 @@ type SWRSession = {
  * }
  * return (<h1>Welcome, {user.name.first_name}</h1>);
  */
-declare const useStytchUser: () => SWRUser;
+declare const useStytchUser: <TAssumeHydrated extends boolean = false>() => SWRUser<TAssumeHydrated>;
 /**
  * Returns the active user's Stytch session.
  * The Stytch SDKs are used for client-side authentication and session management.
@@ -91,7 +95,7 @@ declare const useStytchUser: () => SWRUser;
  *   }
  * }, [session, isInitialized]);
  */
-declare const useStytchSession: () => SWRSession;
+declare const useStytchSession: <TAssumeHydrated extends boolean = false>() => SWRSession<TAssumeHydrated>;
 /**
  * Returns the Stytch client stored in the Stytch context.
  *
@@ -105,12 +109,12 @@ declare const useStytch: <TProjectConfiguration extends Partial<import("@stytch/
 declare const withStytch: <T extends object, TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>(Component: React.ComponentType<T & {
     stytch: StytchClient<TProjectConfiguration>;
 }>) => React.ComponentType<T>;
-declare const withStytchUser: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchUser: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchUser: User | null;
     stytchUserIsInitialized: boolean;
     stytchUserIsFromCache: boolean;
 }>) => React.ComponentType<T>;
-declare const withStytchSession: <T extends object>(Component: React.ComponentType<T & {
+declare const withStytchSession: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
     stytchSession: Session | null;
     stytchSessionIsInitialized: boolean;
     stytchSessionIsFromCache: boolean;
@@ -120,6 +124,20 @@ interface StytchProviderProps<TProjectConfiguration extends StytchProjectConfigu
      * A Stytch client instance, created using either {@link createStytchHeadlessClient} or {@link createStytchUIClient}
      */
     stytch: StytchClient<TProjectConfiguration>;
+    /**
+     * When true, the provider will assume that the component will only be
+     * rendered in a browser environment, either in a single-page application or
+     * after completing hydration of a server-rendered application. This allows
+     * cached values to be retrieved from the browser on the first render, meaning
+     * that the `isInitialized` value returned from Stytch hooks will be `true`
+     * starting from the first render.
+     *
+     * When `false`, the provider will defer initialization until after the first
+     * render, and `isInitialized` will initially be `false`.
+     *
+     * This value defaults to `false` in `@stytch/nextjs`.
+     */
+    assumeHydrated?: boolean;
     children?: ReactNode;
 }
 /**
@@ -134,7 +152,7 @@ interface StytchProviderProps<TProjectConfiguration extends StytchProjectConfigu
  *   </StytchProvider>
  * )
  */
-declare const StytchProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children }: StytchProviderProps<TProjectConfiguration>) => JSX.Element;
+declare const StytchProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children, assumeHydrated }: StytchProviderProps<TProjectConfiguration>) => JSX.Element;
 interface StytchProps<TProjectConfiguration extends StytchProjectConfigurationInput = Stytch.DefaultProjectConfiguration> {
     /**
      * A {@link StytchLoginConfig} object. Add products and product-specific config to this object to change the login methods shown.
@@ -321,5 +339,5 @@ declare const StytchPasskeyRegistration: <TProjectConfiguration extends Partial<
  * />
  */
 declare const IdentityProvider: ({ styles, callbacks }: IdentityProviderProps) => React.JSX.Element;
-export { StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser, StytchLogin, StytchPasswordReset, StytchPasskeyRegistration, IdentityProvider };
-export type { StytchProviderProps };
+export { IdentityProvider, StytchLogin, StytchPasskeyRegistration, StytchPasswordReset, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };
+export type { StytchProviderProps, IdentityProviderProps, StytchProps, StytchResetPasswordProps };

package/dist/index.esm.js

@@ -1,6 +1,6 @@
-import React, { createContext, useContext, useMemo, useEffect, useRef } from 'react';
+import React, { createContext, useContext, useMemo, useCallback, useRef, useEffect } from 'react';
 import { i as invariant, u as useAsyncState, m as mergeWithStableProps, a as useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect-1babb81e.js';
-import { i as isStytchSSRProxy, n as noProviderError, a as noHeadlessClientError } from './StytchSSRProxy-4e34fb34.js';
+import { i as isStytchSSRProxy, n as noProviderError, p as providerMustBeUniqueError, a as noHeadlessClientError } from './StytchSSRProxy-34c789b5.js';
 
 const initialUser = {
     user: null,
@@ -107,30 +107,38 @@ const withStytchSession = (Component) => {
  *   </StytchProvider>
  * )
  */
-const StytchProvider = ({ stytch, children, }) => {
+const StytchProvider = ({ stytch, children, assumeHydrated = false, }) => {
+    invariant(!useIsMounted__INTERNAL(), providerMustBeUniqueError);
+    invariant(!assumeHydrated || typeof window !== 'undefined', 'The `assumeHydrated` prop must be set to `false` when using StytchProvider in a server environment.');
     const ctx = useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
-    const [{ user, session }, setClientState] = useAsyncState({
-        session: initialSession,
-        user: initialUser,
-    });
+    const getHydratedState = useCallback(() => {
+        return {
+            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
+            user: Object.assign(Object.assign({}, stytch.user.getInfo()), { isInitialized: true }),
+        };
+    }, [stytch]);
+    const getInitialState = () => {
+        return {
+            session: initialSession,
+            user: initialUser,
+        };
+    };
+    const [{ user, session }, setClientState] = useAsyncState(() => assumeHydrated ? getHydratedState() : getInitialState());
+    // Store the initial value of `assumeHydrated` in a ref, because it is
+    // logically only relevant for the first render
+    const assumeHydratedRef = useRef(assumeHydrated);
     useEffect(() => {
         if (isStytchSSRProxy(stytch)) {
             return;
         }
-        setClientState({
-            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-            user: Object.assign(Object.assign({}, stytch.user.getInfo()), { isInitialized: true }),
-        });
-        return stytch.onStateChange(() => {
-            setClientState((oldState) => {
-                const newState = {
-                    session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-                    user: Object.assign(Object.assign({}, stytch.user.getInfo()), { isInitialized: true }),
-                };
-                return mergeWithStableProps(oldState, newState);
-            });
-        });
-    }, [setClientState, stytch]);
+        const updateState = () => {
+            setClientState((oldState) => mergeWithStableProps(oldState, getHydratedState()));
+        };
+        if (!assumeHydratedRef.current) {
+            updateState();
+        }
+        return stytch.onStateChange(updateState);
+    }, [getHydratedState, setClientState, stytch]);
     return (React.createElement(StytchContext.Provider, { value: ctx },
         React.createElement(StytchUserContext.Provider, { value: user },
             React.createElement(StytchSessionContext.Provider, { value: session }, children))));

package/dist/index.headless.esm.js

@@ -1,5 +1,5 @@
 import { StytchHeadlessClient } from '@stytch/vanilla-js/headless';
-import { c as createStytchSSRProxy } from './StytchSSRProxy-4e34fb34.js';
+import { c as createStytchSSRProxy } from './StytchSSRProxy-34c789b5.js';
 
 /**
  * Creates a Headless Stytch client object to call the stytch APIs.

package/dist/index.headless.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var headless = require('@stytch/vanilla-js/headless');
-var StytchSSRProxy = require('./StytchSSRProxy-c9d3bc41.js');
+var StytchSSRProxy = require('./StytchSSRProxy-86bc42b3.js');
 
 /**
  * Creates a Headless Stytch client object to call the stytch APIs.

package/dist/index.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var React = require('react');
 var useIsomorphicLayoutEffect = require('./useIsomorphicLayoutEffect-65746ef3.js');
-var StytchSSRProxy = require('./StytchSSRProxy-c9d3bc41.js');
+var StytchSSRProxy = require('./StytchSSRProxy-86bc42b3.js');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -115,30 +115,38 @@ const withStytchSession = (Component) => {
  *   </StytchProvider>
  * )
  */
-const StytchProvider = ({ stytch, children, }) => {
+const StytchProvider = ({ stytch, children, assumeHydrated = false, }) => {
+    useIsomorphicLayoutEffect.invariant(!useIsMounted__INTERNAL(), StytchSSRProxy.providerMustBeUniqueError);
+    useIsomorphicLayoutEffect.invariant(!assumeHydrated || typeof window !== 'undefined', 'The `assumeHydrated` prop must be set to `false` when using StytchProvider in a server environment.');
     const ctx = React.useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
-    const [{ user, session }, setClientState] = useIsomorphicLayoutEffect.useAsyncState({
-        session: initialSession,
-        user: initialUser,
-    });
+    const getHydratedState = React.useCallback(() => {
+        return {
+            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
+            user: Object.assign(Object.assign({}, stytch.user.getInfo()), { isInitialized: true }),
+        };
+    }, [stytch]);
+    const getInitialState = () => {
+        return {
+            session: initialSession,
+            user: initialUser,
+        };
+    };
+    const [{ user, session }, setClientState] = useIsomorphicLayoutEffect.useAsyncState(() => assumeHydrated ? getHydratedState() : getInitialState());
+    // Store the initial value of `assumeHydrated` in a ref, because it is
+    // logically only relevant for the first render
+    const assumeHydratedRef = React.useRef(assumeHydrated);
     React.useEffect(() => {
         if (StytchSSRProxy.isStytchSSRProxy(stytch)) {
             return;
         }
-        setClientState({
-            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-            user: Object.assign(Object.assign({}, stytch.user.getInfo()), { isInitialized: true }),
-        });
-        return stytch.onStateChange(() => {
-            setClientState((oldState) => {
-                const newState = {
-                    session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-                    user: Object.assign(Object.assign({}, stytch.user.getInfo()), { isInitialized: true }),
-                };
-                return useIsomorphicLayoutEffect.mergeWithStableProps(oldState, newState);
-            });
-        });
-    }, [setClientState, stytch]);
+        const updateState = () => {
+            setClientState((oldState) => useIsomorphicLayoutEffect.mergeWithStableProps(oldState, getHydratedState()));
+        };
+        if (!assumeHydratedRef.current) {
+            updateState();
+        }
+        return stytch.onStateChange(updateState);
+    }, [getHydratedState, setClientState, stytch]);
     return (React__default["default"].createElement(StytchContext.Provider, { value: ctx },
         React__default["default"].createElement(StytchUserContext.Provider, { value: user },
             React__default["default"].createElement(StytchSessionContext.Provider, { value: session }, children))));

package/dist/index.ui.esm.js

@@ -1,5 +1,5 @@
 import { StytchUIClient } from '@stytch/vanilla-js';
-import { c as createStytchSSRProxy } from './StytchSSRProxy-4e34fb34.js';
+import { c as createStytchSSRProxy } from './StytchSSRProxy-34c789b5.js';
 
 /**
  * Creates a Stytch UI client object to call the Stytch APIs and render Stytch UI components.

package/dist/index.ui.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var vanillaJs = require('@stytch/vanilla-js');
-var StytchSSRProxy = require('./StytchSSRProxy-c9d3bc41.js');
+var StytchSSRProxy = require('./StytchSSRProxy-86bc42b3.js');
 
 /**
  * Creates a Stytch UI client object to call the Stytch APIs and render Stytch UI components.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stytch/nextjs",
-  "version": "21.4.4",
+  "version": "21.5.0",
   "description": "Stytch's official Next.js Library",
   "main": "./dist/index.js",
   "module": "./dist/index.esm.js",
@@ -15,15 +15,16 @@
     "build": "npm run clean && npm run compile",
     "clean": "rm -rf ./dist",
     "compile": "rollup -c",
-    "dev": "tsc -p tsconfig.build.json --watch"
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "jest"
   },
   "license": "MIT",
   "author": "Stytch",
   "devDependencies": {
-    "@babel/runtime": "7.26.10",
+    "@babel/runtime": "7.27.0",
     "@stytch/internal-tsconfigs": "0.0.0",
     "@stytch/js-utils": "0.0.1",
-    "@stytch/vanilla-js": "5.22.3",
+    "@stytch/vanilla-js": "5.22.7",
     "@testing-library/react": "14.0.0",
     "@types/jest": "29.5.14",
     "eslint-config-custom": "0.0.1",

package/dist/errors-d9d48ed4.d.ts

@@ -1,4 +0,0 @@
-declare const noProviderError: (item: string, provider?: string) => string;
-declare const noHeadlessClientError = "Tried to create a Stytch Login UI element using the Stytch Headless SDK.\nYou must use the UI SDK to use UI elements.\nPlease make sure you are importing createStytchHeadlessClient from @stytch/nextjs/ui and not from @stytch/nextjs/headless.";
-declare const cannotInvokeMethodOnServerError: (path: string) => string;
-export { noProviderError, noHeadlessClientError, cannotInvokeMethodOnServerError };