@stytch/nextjs

@stytch/nextjs

Stytch's Next.js Library

Install

With npm:

npm install @stytch/nextjs @stytch/vanilla-js --save

Documentation

This package contains several entrypoints, depending on if you are using the B2B or B2C stytch product.

// Stytch B2C Product
import { StytchProvider } from '@stytch/nextjs';
import { createStytchUIClient } from '@stytch/nextjs/ui';
// The headless client does not bundle UI elements, and is a much smaller package
import { createStytchHeadlessClient } from '@stytch/nextjs/headless';

// Stytch B2B Product
import { StytchB2B } from '@stytch/nextjs/b2b';
import { createStytchB2BUIClient } from '@stytch/nextjs/b2b/ui';
// The headless client does not bundle UI elements, and is a much smaller package
import { createStytchB2BHeadlessClient } from '@stytch/nextjs/b2b/headless';

For full documentation please refer to Stytch's javascript SDK documentation on https://stytch.com/docs/sdks.

Example Usage

import { StytchProvider } from '@stytch/nextjs';
import { createStytchUIClient } from '@stytch/nextjs/ui';

const stytch = createStytchUIClient('public-token-<find yours in the stytch dashboard>');

// Wrap your App in the StytchProvider
const Root = () => (
  <StytchProvider stytch={stytch}>
    <App />
  </StytchProvider>
);

// Now use Stytch in your components
const App = () => {
  const stytchProps = {
    config: {
      products: ['emailMagicLinks'],
      emailMagicLinksOptions: {
        loginRedirectURL: 'https://example.com/authenticate',
        loginExpirationMinutes: 30,
        signupRedirectURL: 'https://example.com/authenticate',
        signupExpirationMinutes: 30,
        createUserAsPending: true,
      },
    },
    styles: {
      container: { width: '321px' },
      colors: { primary: '#0577CA' },
      fontFamily: '"Helvetica Neue", Helvetica, sans-serif',
    },
    callbacks: {
      onEvent: (message) => console.log(message),
      onError: (message) => console.log(message),
    },
  };

  return (
    <div id="login">
      <StytchLogin config={stytchProps.config} styles={stytchProps.styles} callbacks={stytchProps.callbacks} />
    </div>
  );
};

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, follow the steps below:

Step 1: Install the new libraries

• The core SDK is now bundled in its own module - @stytch/vanilla-js
• We now have a library specifically for NextJS bindings - @stytch/nextjs

# 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.

# 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

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 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

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
• There are some additional changes to the styles config documented here