SSR Considerations

When integrating the Descope Next.js SDK into your application, it's important to handle Server-Side Rendering (SSR) appropriately. This guide covers:

• Rendering Descope components on the client side
• Dynamically importing Descope components
• Understanding SSR implications

Client-Side Rendering Requirement

Descope components rely on browser-specific APIs and cannot be rendered directly during server-side rendering. Attempting to render these components server-side will result in runtime errors.

To avoid these issues, you must render all Descope components exclusively on the client side.

Dynamic Import with SSR Disabled

Use the Next.js dynamic import function with ssr: false to load Descope components on the client side only.

Example:

'use client';
 
import dynamic from 'next/dynamic';
 
const Descope = dynamic(
  () => import('@descope/nextjs-sdk').then(mod => mod.Descope),
  { ssr: false },
);
 
const SignInPage = () => {
  return (
    <Descope
      flowId="sign-up-or-in"
      onSuccess={(e) => console.log('Logged in user:', e.detail.user)}
      onError={(e) => console.error('Login error:', e.detail)}
    />
  );
};
 
export default SignInPage;

Common Errors and Solutions

If you see errors such as:

TypeError: Illegal constructor

or

ReferenceError: window is not defined

These indicate that you're attempting to render Descope components during SSR. Applying dynamic imports with ssr: false will resolve these issues.

When to Use SSR Disabled Imports

Always disable SSR for:

• Descope authentication components (e.g., sign-in flows, widgets).
• Components relying on browser-specific features or APIs.

Impact on SEO and Performance

Disabling SSR for specific authentication components generally does not impact SEO significantly, as these are typically used behind authenticated routes. Performance remains optimal as Next.js efficiently handles client-side hydration.

Examples in Sample Projects

Refer to the following examples for practical implementation:

• App Router Sample
• Pages Router Sample

Summary

By dynamically importing Descope components with SSR disabled, you ensure smooth integration, optimal performance, and secure authentication experiences in your Next.js application.