@stytch/nextjs 0.0.2-0 → 0.3.0

package/README.md

@@ -17,7 +17,7 @@ For full documentation please refer to Stytch's javascript SDK documentation on
 import { StytchProvider } from '@stytch/nextjs';
 import { createStytchUIClient } from '@stytch/nextjs/ui';
 
-const stytch = new createStytchUIClient('public-token-<find yours in the stytch dashboard>');
+const stytch = createStytchUIClient('public-token-<find yours in the stytch dashboard>');
 
 // Wrap your App in the StytchProvider
 ReactDOM.render(
@@ -54,7 +54,7 @@ const App = () => {
 
   return (
     <div id="login">
-      <Stytch config={stytchProps.config} styles={stytchProps.styles} callbacks={stytchProps.callbacks} />
+      <StytchLogin config={stytchProps.config} styles={stytchProps.styles} callbacks={stytchProps.callbacks} />
     </div>
   );
 };
@@ -63,3 +63,98 @@ const App = () => {
 ## Typescript Support
 
 There are built in typescript definitions in the npm package.
+
+## Migrating from @stytch/stytch-react
+
+If you are migrating from [@stytch/stytch-react](https://www.npmjs.com/package/@stytch/stytch-react), follow the steps below:
+
+### Step 1: Install the new libraries
+
+- The core SDK is now bundled in its own module - [@stytch/vanilla-js](https://www.npmjs.com/package/@stytch/vanilla-js)
+- We now have a library specifically for NextJS bindings - [@stytch/nextjs](https://www.npmjs.com/package/@stytch/nextjs)
+
+```shell
+# NPM
+npm install @stytch/vanilla-js @stytch/nextjs
+# Yarn
+yarn add @stytch/vanilla-js @stytch/nextjs
+```
+
+### Step 2: Remove the old SDK
+
+- Remove the `@stytch/stytch-react` package
+- If you are explicitly loading the `stytch.js` script via a blocking `beforeInteractive` tag in the document header, remove it. It isn't needed anymore.
+
+```shell
+# NPM
+npm rm @stytch/stytch-react
+# Yarn
+yarn remove @stytch/stytch-react
+```
+
+### Step 3: Initialize the Stytch client in `_app.js`
+
+- Determine if you need the Headless or UI client. If you plan to use the `<StytchLogin />` component in your application then you should use the the UI client. Otherwise use the Headless client to minimize application bundle size.
+- To create the Stytch Headless client, use `createStytchHeadlessClient` from `@stytch/nextjs/headless`
+- To create the Stytch UI client, use `createStytchUIClient` from `@stytch/nextjs/ui`
+- Pass it into `<StytchProvider />` component from `@stytch/nextjs`
+
+```jsx
+import React from 'react';
+import { StytchProvider } from '@stytch/nextjs';
+import { createStytchHeadlessClient } from '@stytch/nextjs/headless';
+// Or alternately
+// import { createStytchUIClient } from '@stytch/nextjs/ui';
+
+const stytch = createStytchHeadlessClient(process.env.NEXT_PUBLIC_STYTCH_PUBLIC_TOKEN);
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <StytchProvider stytch={stytch}>
+      <Component {...pageProps} />
+    </StytchProvider>
+  );
+}
+
+export default MyApp;
+```
+
+### Step 4: Update calls to `useStytchUser` , `useStytchSession`, and `useStytchLazy`
+
+- `useStytchUser` and `useStytchSession` hooks now return envelope objects - `{ user, isInitialized, isCached }` and `{ session, isInitialized, isCached }` respectively.
+  - In SSR/SSG contexts, as well as the first clientside render, `user`/`session` will be null and `isInitialized` will be false
+  - The SDK will read `user`/`session` out of persistent storage, and rerender with `isCached: true` - at this point you’re reading the [stale-while-revalidating](https://swr.vercel.app/) value
+  - The SDK will make network requests to pull the most up-to-date user and session objects, and serve them with `isCached: false`
+- `useStytchLazy` is no longer required - you may always call `useStytch` now
+
+```jsx
+import React, { useEffect } from 'react';
+import { useRouter } from 'next/router';
+import { useStytchUser } from '@stytch/nextjs';
+
+export default function Profile() {
+  const router = useRouter();
+  const { user, isInitialized } = useStytchUser();
+
+  useEffect(() => {
+    if (isInitialized && user === null) {
+      router.push('/login');
+    }
+  }, [user, isInitialized]);
+
+  return (
+    <Layout>
+      <h1>Your Profile</h1>
+      <pre>{JSON.stringify(user, null, 2)}</pre>
+    </Layout>
+  );
+}
+```
+
+### Step 5: UI Naming Changes
+
+We've made a number of small changes to our naming conventions to make the API cleaner and easier to understand.
+
+- The `<Stytch />` login component is now called `<StytchLogin />`
+- The `OAuthProvidersTypes` enum is now called `OAuthProviders`
+- The `SDKProductTypes` enum is now called `Products`

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 /// <reference types="react" />
 import React from "react";
 import { ReactNode } from "react";
-import { User, Session, StytchUIClient, Callbacks, Config } from "@stytch/vanilla-js";
+import { User, Session, StytchUIClient, Callbacks, StytchLoginConfig, StyleConfig } from "@stytch/vanilla-js";
 import { StytchHeadlessClient } from "@stytch/vanilla-js/headless";
 /**
- * TODO: How much of this package can be reused from stytch-react?
+ * The Stytch Client object passed in to <StytchProvider /> in your `_app.js`.
+ * Either a StytchUIClient or StytchHeadlessClient.
  */
 type StytchClient = StytchUIClient | StytchHeadlessClient;
 type SWRUser = {
@@ -13,11 +14,7 @@ type SWRUser = {
     isInitialized: false;
 } | {
     user: User | null;
-    fromCache: true;
-    isInitialized: true;
-} | {
-    user: User | null;
-    fromCache: false;
+    fromCache: boolean;
     isInitialized: true;
 };
 type SWRSession = {
@@ -26,15 +23,50 @@ type SWRSession = {
     isInitialized: false;
 } | {
     session: Session | null;
-    fromCache: true;
-    isInitialized: true;
-} | {
-    session: Session | null;
-    fromCache: false;
+    fromCache: boolean;
     isInitialized: true;
 };
+/**
+ * Returns the active User.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * @example
+ * const {user, isInitialized, fromCache} = useStytchUser();
+ * if (!isInitialized) {
+ *     return <p>Loading...</p>;
+ * }
+ * return (<h1>Welcome, {user.name.first_name}</h1>);
+ */
 declare const useStytchUser: () => SWRUser;
+/**
+ * Returns the user's active Stytch session.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * @example
+ * const {session, isInitialized, fromCache} = useStytchSession();
+ * useEffect(() => {
+ *   if (!isInitialized) {
+ *     return;
+ *   }
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session, isInitialized]);
+ */
 declare const useStytchSession: () => SWRSession;
+/**
+ * Returns the Stytch client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytch();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
 declare const useStytch: () => StytchClient;
 declare const withStytch: <T extends object>(Component: React.ComponentType<T & {
     stytch: StytchClient;
@@ -49,29 +81,124 @@ declare const withStytchSession: <T extends object>(Component: React.ComponentTy
     stytchSessionIsInitialized: boolean;
     stytchSessionIsFromCache: boolean;
 }>) => React.ComponentType<T>;
-type StytchProviderProps = {
+interface StytchProviderProps {
+    /**
+     * A Stytch client instance, created using either {@link createStytchHeadlessClient} or {@link createStytchUIClient}
+     */
     stytch: StytchClient;
     children?: ReactNode;
-};
+}
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in `_app.js` in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = createStytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ */
 declare const StytchProvider: ({ stytch, children }: StytchProviderProps) => JSX.Element;
+interface StytchProps {
+    /**
+     * A {@link StytchLoginConfig} object. Add products and product-specific config to this object to change the login methods shown.
+     *
+     * @example
+     * {
+     *   products: ['crypto', 'otps']
+     * }
+     *
+     * @example
+     * {
+     *   products: ['emailMagicLinks'>]
+     *   emailMagicLinksOptions: {
+     *     loginRedirectURL: 'https://example.com/authenticate',
+     *     signupRedirectURL: 'https://example.com/authenticate',
+     *   }
+     * }
+     *
+     * @example
+     * {
+     *   products: ['oauth'>]
+     *   oauthOptions: {
+     *   providers: [
+     *       { type: 'google', one_tap: true, position: 'embedded' },
+     *       { type: 'microsoft' },
+     *       { type: 'apple' },
+     *       { type: 'facebook' },
+     *     ],
+     *   }
+     * }
+     */
+    config: StytchLoginConfig;
+    /**
+     * An optional {@link StyleConfig} to customize the look and feel of the screen.
+     *
+     * @example
+     * {
+     *    fontFamily: 'Arial, Helvetica, sans-serif',
+     *    width: '360px',
+     *    primaryColor: '#19303D',
+     * }
+     */
+    styles?: StyleConfig;
+    /**
+     * An optional {@link Callbacks} object.
+     *
+     * @example
+     * {
+     *   onError: ({message}) => {
+     *      console.error('Stytch login screen error', message)
+     *   }
+     * }
+     *
+     * @example
+     * {
+     *   onEvent: ({type, data}) => {
+     *     if(type === StytchEventType.CryptoWalletAuthenticate) {
+     *       console.log('Logged in with crypto wallet', data);
+     *     }
+     *   }
+     * }
+     */
+    callbacks?: Callbacks;
+}
 /**
- * Stytch JS React Component
+ * The Stytch Login Screen component.
+ * This component can only be used with the Stytch UI Client - use {@link createStytchUIClient}
+ * in your `_app.jsx` file.
+ *
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * <StytchLogin
+ *   config={{
+ *     products: ['emailMagicLinks', 'oauth'],
+ *     emailMagicLinksOptions: {
+ *       loginRedirectURL: 'https://example.com/authenticate',
+ *       signupRedirectURL: 'https://example.com/authenticate',
+ *     },
+ *     oauthOptions: {
+ *      providers: [{ type: OAuthProviders.Google }, { type: OAuthProviders.Microsoft }],
+ *    },
+ *   }}
+ *   styles={{
+ *     fontFamily: '"Helvetica New", Helvetica, sans-serif',
+ *     primaryColor: '#0577CA',
+ *     width: '321px',
+ *   }}
+ *   callbacks={{
+ *     onEvent: (event) => console.log(event)
+ *   }}
+ * />
  *
- * [Documentation](https://stytch.com/docs/javascript-sdk)
+ * @param config - A {@link StytchLoginConfig} object
+ * @param styles - An optional {@link StyleConfig} to customize the look and feel of the screen.
+ * @param callbacks - An optional {@link Callbacks} object
  */
-declare const Stytch: ({ config, styles, callbacks }: {
-    config: Config;
-    styles?: Partial<{
-        fontFamily: string;
-        width: string;
-        primaryColor: string;
-        primaryTextColor: string;
-        secondaryTextColor: string;
-        lightGrey: string;
-        darkGrey: string;
-        hideHeaderText: boolean;
-    }> | undefined;
-    callbacks?: Callbacks | undefined;
-}) => JSX.Element;
-export { StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser, Stytch };
+declare const StytchLogin: ({ config, styles, callbacks }: StytchProps) => JSX.Element;
+export { StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser, StytchLogin };
 export type { StytchProviderProps };

package/dist/index.esm.d.ts

@@ -1,10 +1,11 @@
 /// <reference types="react" />
 import React from "react";
 import { ReactNode } from "react";
-import { User, Session, StytchUIClient, Callbacks, Config } from "@stytch/vanilla-js";
+import { User, Session, StytchUIClient, Callbacks, StytchLoginConfig, StyleConfig } from "@stytch/vanilla-js";
 import { StytchHeadlessClient } from "@stytch/vanilla-js/headless";
 /**
- * TODO: How much of this package can be reused from stytch-react?
+ * The Stytch Client object passed in to <StytchProvider /> in your `_app.js`.
+ * Either a StytchUIClient or StytchHeadlessClient.
  */
 type StytchClient = StytchUIClient | StytchHeadlessClient;
 type SWRUser = {
@@ -13,11 +14,7 @@ type SWRUser = {
     isInitialized: false;
 } | {
     user: User | null;
-    fromCache: true;
-    isInitialized: true;
-} | {
-    user: User | null;
-    fromCache: false;
+    fromCache: boolean;
     isInitialized: true;
 };
 type SWRSession = {
@@ -26,15 +23,50 @@ type SWRSession = {
     isInitialized: false;
 } | {
     session: Session | null;
-    fromCache: true;
-    isInitialized: true;
-} | {
-    session: Session | null;
-    fromCache: false;
+    fromCache: boolean;
     isInitialized: true;
 };
+/**
+ * Returns the active User.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * @example
+ * const {user, isInitialized, fromCache} = useStytchUser();
+ * if (!isInitialized) {
+ *     return <p>Loading...</p>;
+ * }
+ * return (<h1>Welcome, {user.name.first_name}</h1>);
+ */
 declare const useStytchUser: () => SWRUser;
+/**
+ * Returns the user's active Stytch session.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * @example
+ * const {session, isInitialized, fromCache} = useStytchSession();
+ * useEffect(() => {
+ *   if (!isInitialized) {
+ *     return;
+ *   }
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session, isInitialized]);
+ */
 declare const useStytchSession: () => SWRSession;
+/**
+ * Returns the Stytch client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytch();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
 declare const useStytch: () => StytchClient;
 declare const withStytch: <T extends object>(Component: React.ComponentType<T & {
     stytch: StytchClient;
@@ -49,29 +81,124 @@ declare const withStytchSession: <T extends object>(Component: React.ComponentTy
     stytchSessionIsInitialized: boolean;
     stytchSessionIsFromCache: boolean;
 }>) => React.ComponentType<T>;
-type StytchProviderProps = {
+interface StytchProviderProps {
+    /**
+     * A Stytch client instance, created using either {@link createStytchHeadlessClient} or {@link createStytchUIClient}
+     */
     stytch: StytchClient;
     children?: ReactNode;
-};
+}
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in `_app.js` in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = createStytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ */
 declare const StytchProvider: ({ stytch, children }: StytchProviderProps) => JSX.Element;
+interface StytchProps {
+    /**
+     * A {@link StytchLoginConfig} object. Add products and product-specific config to this object to change the login methods shown.
+     *
+     * @example
+     * {
+     *   products: ['crypto', 'otps']
+     * }
+     *
+     * @example
+     * {
+     *   products: ['emailMagicLinks'>]
+     *   emailMagicLinksOptions: {
+     *     loginRedirectURL: 'https://example.com/authenticate',
+     *     signupRedirectURL: 'https://example.com/authenticate',
+     *   }
+     * }
+     *
+     * @example
+     * {
+     *   products: ['oauth'>]
+     *   oauthOptions: {
+     *   providers: [
+     *       { type: 'google', one_tap: true, position: 'embedded' },
+     *       { type: 'microsoft' },
+     *       { type: 'apple' },
+     *       { type: 'facebook' },
+     *     ],
+     *   }
+     * }
+     */
+    config: StytchLoginConfig;
+    /**
+     * An optional {@link StyleConfig} to customize the look and feel of the screen.
+     *
+     * @example
+     * {
+     *    fontFamily: 'Arial, Helvetica, sans-serif',
+     *    width: '360px',
+     *    primaryColor: '#19303D',
+     * }
+     */
+    styles?: StyleConfig;
+    /**
+     * An optional {@link Callbacks} object.
+     *
+     * @example
+     * {
+     *   onError: ({message}) => {
+     *      console.error('Stytch login screen error', message)
+     *   }
+     * }
+     *
+     * @example
+     * {
+     *   onEvent: ({type, data}) => {
+     *     if(type === StytchEventType.CryptoWalletAuthenticate) {
+     *       console.log('Logged in with crypto wallet', data);
+     *     }
+     *   }
+     * }
+     */
+    callbacks?: Callbacks;
+}
 /**
- * Stytch JS React Component
+ * The Stytch Login Screen component.
+ * This component can only be used with the Stytch UI Client - use {@link createStytchUIClient}
+ * in your `_app.jsx` file.
+ *
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * <StytchLogin
+ *   config={{
+ *     products: ['emailMagicLinks', 'oauth'],
+ *     emailMagicLinksOptions: {
+ *       loginRedirectURL: 'https://example.com/authenticate',
+ *       signupRedirectURL: 'https://example.com/authenticate',
+ *     },
+ *     oauthOptions: {
+ *      providers: [{ type: OAuthProviders.Google }, { type: OAuthProviders.Microsoft }],
+ *    },
+ *   }}
+ *   styles={{
+ *     fontFamily: '"Helvetica New", Helvetica, sans-serif',
+ *     primaryColor: '#0577CA',
+ *     width: '321px',
+ *   }}
+ *   callbacks={{
+ *     onEvent: (event) => console.log(event)
+ *   }}
+ * />
  *
- * [Documentation](https://stytch.com/docs/javascript-sdk)
+ * @param config - A {@link StytchLoginConfig} object
+ * @param styles - An optional {@link StyleConfig} to customize the look and feel of the screen.
+ * @param callbacks - An optional {@link Callbacks} object
  */
-declare const Stytch: ({ config, styles, callbacks }: {
-    config: Config;
-    styles?: Partial<{
-        fontFamily: string;
-        width: string;
-        primaryColor: string;
-        primaryTextColor: string;
-        secondaryTextColor: string;
-        lightGrey: string;
-        darkGrey: string;
-        hideHeaderText: boolean;
-    }> | undefined;
-    callbacks?: Callbacks | undefined;
-}) => JSX.Element;
-export { StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser, Stytch };
+declare const StytchLogin: ({ config, styles, callbacks }: StytchProps) => JSX.Element;
+export { StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser, StytchLogin };
 export type { StytchProviderProps };

package/dist/index.esm.js

@@ -49,16 +49,55 @@ const StytchUserContext = createContext(initialUser);
 const StytchSessionContext = createContext(initialSession);
 const useIsMounted__INTERNAL = () => useContext(StytchContext).isMounted;
 const isUIClient = (client) => {
-    return client.mount !== undefined;
+    return client.mountLogin !== undefined;
 };
+/**
+ * Returns the active User.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * @example
+ * const {user, isInitialized, fromCache} = useStytchUser();
+ * if (!isInitialized) {
+ *     return <p>Loading...</p>;
+ * }
+ * return (<h1>Welcome, {user.name.first_name}</h1>);
+ */
 const useStytchUser = () => {
     invariant(useIsMounted__INTERNAL(), noProviderError('useStytchUser'));
     return useContext(StytchUserContext);
 };
+/**
+ * Returns the user's active Stytch session.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * @example
+ * const {session, isInitialized, fromCache} = useStytchSession();
+ * useEffect(() => {
+ *   if (!isInitialized) {
+ *     return;
+ *   }
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session, isInitialized]);
+ */
 const useStytchSession = () => {
     invariant(useIsMounted__INTERNAL(), noProviderError('useStytchSession'));
     return useContext(StytchSessionContext);
 };
+/**
+ * Returns the Stytch client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytch();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
 const useStytch = () => {
     const ctx = useContext(StytchContext);
     invariant(ctx.isMounted, noProviderError('useStytch'));
@@ -67,7 +106,7 @@ const useStytch = () => {
 const withStytch = (Component) => {
     const WithStytch = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytch'));
-        return React.createElement(Component, { ...props, stytch: useStytch() });
+        return React.createElement(Component, Object.assign({}, props, { stytch: useStytch() }));
     };
     WithStytch.displayName = `withStytch(${Component.displayName || Component.name || 'Component'})`;
     return WithStytch;
@@ -76,7 +115,7 @@ const withStytchUser = (Component) => {
     const WithStytchUser = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytchUser'));
         const { user, isInitialized, fromCache } = useStytchUser();
-        return (React.createElement(Component, { ...props, stytchUser: user, stytchUserIsInitialized: isInitialized, stytchUserIsFromCache: fromCache }));
+        return (React.createElement(Component, Object.assign({}, props, { stytchUser: user, stytchUserIsInitialized: isInitialized, stytchUserIsFromCache: fromCache })));
     };
     WithStytchUser.displayName = `withStytchUser(${Component.displayName || Component.name || 'Component'})`;
     return WithStytchUser;
@@ -85,13 +124,24 @@ const withStytchSession = (Component) => {
     const WithStytchSession = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytchSession'));
         const { session, isInitialized, fromCache } = useStytchSession();
-        return (React.createElement(Component, { ...props, stytchSession: session, stytchSessionIsInitialized: isInitialized, stytchSessionIsFromCache: fromCache }));
+        return (React.createElement(Component, Object.assign({}, props, { stytchSession: session, stytchSessionIsInitialized: isInitialized, stytchSessionIsFromCache: fromCache })));
     };
     WithStytchSession.displayName = `withStytchSession(${Component.displayName || Component.name || 'Component'})`;
     return WithStytchSession;
 };
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in `_app.js` in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = createStytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ */
 const StytchProvider = ({ stytch, children }) => {
-    // invariant(!useIsMounted__INTERNAL(), providerMustBeUniqueError);
     const ctx = useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
     const [user, setUser] = useAsyncState(initialUser);
     const [session, setSession] = useAsyncState(initialSession);
@@ -116,8 +166,8 @@ const StytchProvider = ({ stytch, children }) => {
             unsubscribeSession();
         };
     }, [stytch, setUser, setSession]);
-    const finalSess = session.isInitialized === user.isInitialized ? session : initialSession;
-    const finalUser = session.isInitialized === user.isInitialized ? user : initialUser;
+    const finalSess = !!session.session === !!user.user ? session : initialSession;
+    const finalUser = !!session.session === !!user.user ? user : initialUser;
     return (React.createElement(StytchContext.Provider, { value: ctx },
         React.createElement(StytchUserContext.Provider, { value: finalUser },
             React.createElement(StytchSessionContext.Provider, { value: finalSess }, children))));
@@ -127,12 +177,41 @@ const StytchProvider = ({ stytch, children }) => {
 const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 
 /**
- * Stytch JS React Component
+ * The Stytch Login Screen component.
+ * This component can only be used with the Stytch UI Client - use {@link createStytchUIClient}
+ * in your `_app.jsx` file.
  *
- * [Documentation](https://stytch.com/docs/javascript-sdk)
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * <StytchLogin
+ *   config={{
+ *     products: ['emailMagicLinks', 'oauth'],
+ *     emailMagicLinksOptions: {
+ *       loginRedirectURL: 'https://example.com/authenticate',
+ *       signupRedirectURL: 'https://example.com/authenticate',
+ *     },
+ *     oauthOptions: {
+ *      providers: [{ type: OAuthProviders.Google }, { type: OAuthProviders.Microsoft }],
+ *    },
+ *   }}
+ *   styles={{
+ *     fontFamily: '"Helvetica New", Helvetica, sans-serif',
+ *     primaryColor: '#0577CA',
+ *     width: '321px',
+ *   }}
+ *   callbacks={{
+ *     onEvent: (event) => console.log(event)
+ *   }}
+ * />
+ *
+ * @param config - A {@link StytchLoginConfig} object
+ * @param styles - An optional {@link StyleConfig} to customize the look and feel of the screen.
+ * @param callbacks - An optional {@link Callbacks} object
  */
-const Stytch = ({ config, styles, callbacks, }) => {
-    invariant(useIsMounted__INTERNAL(), noProviderError('<Stytch />'));
+const StytchLogin = ({ config, styles, callbacks }) => {
+    invariant(useIsMounted__INTERNAL(), noProviderError('<StytchLogin />'));
     const stytchClient = useStytch();
     const containerEl = useRef(null);
     useIsomorphicLayoutEffect(() => {
@@ -142,20 +221,18 @@ const Stytch = ({ config, styles, callbacks, }) => {
         if (!containerEl.current) {
             return;
         }
-        if (containerEl.current.id) {
-            return;
+        if (!containerEl.current.id) {
+            const randId = Math.floor(Math.random() * 1e6);
+            containerEl.current.id = `stytch-magic-link-${randId}`;
         }
-        const randId = Math.floor(Math.random() * 1e6);
-        const elementId = `stytch-magic-link-${randId}`;
-        containerEl.current.id = elementId;
-        stytchClient.mount({
+        stytchClient.mountLogin({
             config,
             callbacks,
-            elementId: `#${elementId}`,
+            elementId: `#${containerEl.current.id}`,
             styles,
         });
-    }, [stytchClient]);
+    }, [stytchClient, config, styles, callbacks]);
     return React.createElement("div", { ref: containerEl });
 };
 
-export { Stytch, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };
+export { StytchLogin, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };

package/dist/index.headless.d.ts

@@ -1,3 +1,16 @@
 import { StytchHeadlessClient } from "@stytch/vanilla-js/headless";
+/**
+ * Creates a Headless Stytch client object to call the stytch APIs.
+ * The Stytch client is not available serverside.
+ * @example
+ * const stytch = createStytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ * @returns A {@link StytchHeadlessClient}
+ */
 declare const createStytchHeadlessClient: (_PUBLIC_TOKEN: string) => StytchHeadlessClient;
 export { createStytchHeadlessClient };

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

@@ -1,3 +1,16 @@
 import { StytchHeadlessClient } from "@stytch/vanilla-js/headless";
+/**
+ * Creates a Headless Stytch client object to call the stytch APIs.
+ * The Stytch client is not available serverside.
+ * @example
+ * const stytch = createStytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ * @returns A {@link StytchHeadlessClient}
+ */
 declare const createStytchHeadlessClient: (_PUBLIC_TOKEN: string) => StytchHeadlessClient;
 export { createStytchHeadlessClient };

package/dist/index.headless.esm.js

@@ -38,6 +38,19 @@ const createProxy = (path) => {
 };
 const createStytchSSRProxy = () => createProxy('stytch');
 
+/**
+ * Creates a Headless Stytch client object to call the stytch APIs.
+ * The Stytch client is not available serverside.
+ * @example
+ * const stytch = createStytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ * @returns A {@link StytchHeadlessClient}
+ */
 const createStytchHeadlessClient = (...args) => {
     if (typeof window === 'undefined') {
         return createStytchSSRProxy();

package/dist/index.headless.js

@@ -42,6 +42,19 @@ const createProxy = (path) => {
 };
 const createStytchSSRProxy = () => createProxy('stytch');
 
+/**
+ * Creates a Headless Stytch client object to call the stytch APIs.
+ * The Stytch client is not available serverside.
+ * @example
+ * const stytch = createStytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ * @returns A {@link StytchHeadlessClient}
+ */
 const createStytchHeadlessClient = (...args) => {
     if (typeof window === 'undefined') {
         return createStytchSSRProxy();

package/dist/index.js

@@ -57,16 +57,55 @@ const StytchUserContext = React.createContext(initialUser);
 const StytchSessionContext = React.createContext(initialSession);
 const useIsMounted__INTERNAL = () => React.useContext(StytchContext).isMounted;
 const isUIClient = (client) => {
-    return client.mount !== undefined;
+    return client.mountLogin !== undefined;
 };
+/**
+ * Returns the active User.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * @example
+ * const {user, isInitialized, fromCache} = useStytchUser();
+ * if (!isInitialized) {
+ *     return <p>Loading...</p>;
+ * }
+ * return (<h1>Welcome, {user.name.first_name}</h1>);
+ */
 const useStytchUser = () => {
     invariant(useIsMounted__INTERNAL(), noProviderError('useStytchUser'));
     return React.useContext(StytchUserContext);
 };
+/**
+ * Returns the user's active Stytch session.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * @example
+ * const {session, isInitialized, fromCache} = useStytchSession();
+ * useEffect(() => {
+ *   if (!isInitialized) {
+ *     return;
+ *   }
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session, isInitialized]);
+ */
 const useStytchSession = () => {
     invariant(useIsMounted__INTERNAL(), noProviderError('useStytchSession'));
     return React.useContext(StytchSessionContext);
 };
+/**
+ * Returns the Stytch client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytch();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
 const useStytch = () => {
     const ctx = React.useContext(StytchContext);
     invariant(ctx.isMounted, noProviderError('useStytch'));
@@ -75,7 +114,7 @@ const useStytch = () => {
 const withStytch = (Component) => {
     const WithStytch = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytch'));
-        return React__default["default"].createElement(Component, { ...props, stytch: useStytch() });
+        return React__default["default"].createElement(Component, Object.assign({}, props, { stytch: useStytch() }));
     };
     WithStytch.displayName = `withStytch(${Component.displayName || Component.name || 'Component'})`;
     return WithStytch;
@@ -84,7 +123,7 @@ const withStytchUser = (Component) => {
     const WithStytchUser = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytchUser'));
         const { user, isInitialized, fromCache } = useStytchUser();
-        return (React__default["default"].createElement(Component, { ...props, stytchUser: user, stytchUserIsInitialized: isInitialized, stytchUserIsFromCache: fromCache }));
+        return (React__default["default"].createElement(Component, Object.assign({}, props, { stytchUser: user, stytchUserIsInitialized: isInitialized, stytchUserIsFromCache: fromCache })));
     };
     WithStytchUser.displayName = `withStytchUser(${Component.displayName || Component.name || 'Component'})`;
     return WithStytchUser;
@@ -93,13 +132,24 @@ const withStytchSession = (Component) => {
     const WithStytchSession = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytchSession'));
         const { session, isInitialized, fromCache } = useStytchSession();
-        return (React__default["default"].createElement(Component, { ...props, stytchSession: session, stytchSessionIsInitialized: isInitialized, stytchSessionIsFromCache: fromCache }));
+        return (React__default["default"].createElement(Component, Object.assign({}, props, { stytchSession: session, stytchSessionIsInitialized: isInitialized, stytchSessionIsFromCache: fromCache })));
     };
     WithStytchSession.displayName = `withStytchSession(${Component.displayName || Component.name || 'Component'})`;
     return WithStytchSession;
 };
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in `_app.js` in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = createStytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ */
 const StytchProvider = ({ stytch, children }) => {
-    // invariant(!useIsMounted__INTERNAL(), providerMustBeUniqueError);
     const ctx = React.useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
     const [user, setUser] = useAsyncState(initialUser);
     const [session, setSession] = useAsyncState(initialSession);
@@ -124,8 +174,8 @@ const StytchProvider = ({ stytch, children }) => {
             unsubscribeSession();
         };
     }, [stytch, setUser, setSession]);
-    const finalSess = session.isInitialized === user.isInitialized ? session : initialSession;
-    const finalUser = session.isInitialized === user.isInitialized ? user : initialUser;
+    const finalSess = !!session.session === !!user.user ? session : initialSession;
+    const finalUser = !!session.session === !!user.user ? user : initialUser;
     return (React__default["default"].createElement(StytchContext.Provider, { value: ctx },
         React__default["default"].createElement(StytchUserContext.Provider, { value: finalUser },
             React__default["default"].createElement(StytchSessionContext.Provider, { value: finalSess }, children))));
@@ -135,12 +185,41 @@ const StytchProvider = ({ stytch, children }) => {
 const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
 
 /**
- * Stytch JS React Component
+ * The Stytch Login Screen component.
+ * This component can only be used with the Stytch UI Client - use {@link createStytchUIClient}
+ * in your `_app.jsx` file.
  *
- * [Documentation](https://stytch.com/docs/javascript-sdk)
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * <StytchLogin
+ *   config={{
+ *     products: ['emailMagicLinks', 'oauth'],
+ *     emailMagicLinksOptions: {
+ *       loginRedirectURL: 'https://example.com/authenticate',
+ *       signupRedirectURL: 'https://example.com/authenticate',
+ *     },
+ *     oauthOptions: {
+ *      providers: [{ type: OAuthProviders.Google }, { type: OAuthProviders.Microsoft }],
+ *    },
+ *   }}
+ *   styles={{
+ *     fontFamily: '"Helvetica New", Helvetica, sans-serif',
+ *     primaryColor: '#0577CA',
+ *     width: '321px',
+ *   }}
+ *   callbacks={{
+ *     onEvent: (event) => console.log(event)
+ *   }}
+ * />
+ *
+ * @param config - A {@link StytchLoginConfig} object
+ * @param styles - An optional {@link StyleConfig} to customize the look and feel of the screen.
+ * @param callbacks - An optional {@link Callbacks} object
  */
-const Stytch = ({ config, styles, callbacks, }) => {
-    invariant(useIsMounted__INTERNAL(), noProviderError('<Stytch />'));
+const StytchLogin = ({ config, styles, callbacks }) => {
+    invariant(useIsMounted__INTERNAL(), noProviderError('<StytchLogin />'));
     const stytchClient = useStytch();
     const containerEl = React.useRef(null);
     useIsomorphicLayoutEffect(() => {
@@ -150,23 +229,21 @@ const Stytch = ({ config, styles, callbacks, }) => {
         if (!containerEl.current) {
             return;
         }
-        if (containerEl.current.id) {
-            return;
+        if (!containerEl.current.id) {
+            const randId = Math.floor(Math.random() * 1e6);
+            containerEl.current.id = `stytch-magic-link-${randId}`;
         }
-        const randId = Math.floor(Math.random() * 1e6);
-        const elementId = `stytch-magic-link-${randId}`;
-        containerEl.current.id = elementId;
-        stytchClient.mount({
+        stytchClient.mountLogin({
             config,
             callbacks,
-            elementId: `#${elementId}`,
+            elementId: `#${containerEl.current.id}`,
             styles,
         });
-    }, [stytchClient]);
+    }, [stytchClient, config, styles, callbacks]);
     return React__default["default"].createElement("div", { ref: containerEl });
 };
 
-exports.Stytch = Stytch;
+exports.StytchLogin = StytchLogin;
 exports.StytchProvider = StytchProvider;
 exports.useStytch = useStytch;
 exports.useStytchSession = useStytchSession;

package/dist/index.ui.d.ts

@@ -1,3 +1,17 @@
 import { StytchUIClient } from "@stytch/vanilla-js";
+/**
+ * Creates a Stytch UI client object to call the Stytch APIs and render Stytch UI components.
+ * The Stytch client is not available serverside.
+ * If you do not use Stytch UI components, use {@link createStytchHeadlessClient} to reduce your bundle size.
+ * @example
+ * const stytch = createStytchUIClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ * @returns A {@link StytchUIClient}
+ */
 declare const createStytchUIClient: (_PUBLIC_TOKEN: string) => StytchUIClient;
 export { createStytchUIClient };

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

@@ -1,3 +1,17 @@
 import { StytchUIClient } from "@stytch/vanilla-js";
+/**
+ * Creates a Stytch UI client object to call the Stytch APIs and render Stytch UI components.
+ * The Stytch client is not available serverside.
+ * If you do not use Stytch UI components, use {@link createStytchHeadlessClient} to reduce your bundle size.
+ * @example
+ * const stytch = createStytchUIClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ * @returns A {@link StytchUIClient}
+ */
 declare const createStytchUIClient: (_PUBLIC_TOKEN: string) => StytchUIClient;
 export { createStytchUIClient };

package/dist/index.ui.esm.js

@@ -38,6 +38,20 @@ const createProxy = (path) => {
 };
 const createStytchSSRProxy = () => createProxy('stytch');
 
+/**
+ * Creates a Stytch UI client object to call the Stytch APIs and render Stytch UI components.
+ * The Stytch client is not available serverside.
+ * If you do not use Stytch UI components, use {@link createStytchHeadlessClient} to reduce your bundle size.
+ * @example
+ * const stytch = createStytchUIClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ * @returns A {@link StytchUIClient}
+ */
 const createStytchUIClient = (...args) => {
     if (typeof window === 'undefined') {
         return createStytchSSRProxy();

package/dist/index.ui.js

@@ -42,6 +42,20 @@ const createProxy = (path) => {
 };
 const createStytchSSRProxy = () => createProxy('stytch');
 
+/**
+ * Creates a Stytch UI client object to call the Stytch APIs and render Stytch UI components.
+ * The Stytch client is not available serverside.
+ * If you do not use Stytch UI components, use {@link createStytchHeadlessClient} to reduce your bundle size.
+ * @example
+ * const stytch = createStytchUIClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>
+ * )
+ * @returns A {@link StytchUIClient}
+ */
 const createStytchUIClient = (...args) => {
     if (typeof window === 'undefined') {
         return createStytchSSRProxy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stytch/nextjs",
-  "version": "0.0.2-0",
+  "version": "0.3.0",
   "description": "Stytch's official Next.js Library",
   "main": "./dist/index.js",
   "module": "./dist/index.esm.js",
@@ -21,15 +21,26 @@
   "author": "Stytch",
   "devDependencies": {
     "@babel/runtime": "^7.18.6",
-    "@stytch/vanilla-js": "0.0.2-0",
+    "@stytch/vanilla-js": "0.2.0",
     "eslint-config-custom": "0.0.0",
     "rollup": "^2.56.3",
-    "typescript": "^4.5.3"
+    "typescript": "4.7.4"
   },
   "peerDependencies": {
-    "@stytch/vanilla-js": "^0.0.2-0",
+    "@stytch/vanilla-js": "^0.2.0",
     "react": ">= 17.0.2",
     "react-dom": ">= 17.0.2"
   },
-  "stableVersion": "0.0.1"
-}
+  "homepage": "https://stytch.com/docs/sdks/javascript-sdk",
+  "keywords": [
+    "stytch",
+    "react",
+    "nextjs",
+    "typescript",
+    "auth",
+    "authentication",
+    "session",
+    "jwt",
+    "user"
+  ]
+}