> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/products/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/sdk-loader-idv/integrations/nextjs.md).

# Nextjs

Next.js is a React framework for creating modern web applications with features like server-side rendering (SSR), static site generation (SSG), and hybrid rendering. This guide explains how to integrate the SDK Loader into Next.js applications.

{% hint style="warning" %}
Since the SDK Loader uses browser APIs (DOM manipulation, dynamic script loading), it must run **only on the client side**. Next.js offers several ways to do this depending on your routing approach.
{% endhint %}

## Environment configuration

Create a file `.env` at the root of your project:

```bash
NEXT_PUBLIC_API_KEY=YOUR_API_KEY
```

{% hint style="warning" %}
Variables with the prefix `NEXT_PUBLIC_` are exposed to the browser.
{% endhint %}

## App Router (Next.js 16+)

For the App Router, use the `'use client'` directive to ensure the component runs on the client.

### Example: app/sdk/page.tsx

{% code title="app/sdk/page.tsx" %}

```tsx
'use client';

import { useEffect } from 'react';
import { loadSdk } from '@facephi/sdk-loader';

export default function SdkPage() {
  useEffect(() => {
    const initializeSdk = async () => {
      const apiKey = process.env.NEXT_PUBLIC_API_KEY || '';

      const sdkElement = await loadSdk({
        apiKey,
        containerId: 'sdk-container',
      });

      if (sdkElement) {
        sdkElement.addEventListener('emitIDVIntegration', (event) => {
          console.log('emitIDVIntegration:', event);
        });
      }
    };

    initializeSdk();
  }, []);

  return (
    <main>
      <section>
        <div id="sdk-container" />
      </section>
    </main>
  );
}
```

{% endcode %}

{% hint style="warning" %}
The `'use client'` directive is necessary because the SDK Loader uses browser APIs.
{% endhint %}

## Pages Router (Next.js 16+)

For the Pages Router, use `next/dynamic` with `ssr: false` to disable server-side rendering of the SDK component.

### Example: pages/sdk.tsx

{% code title="pages/sdk.tsx" %}

```tsx
import { useEffect } from 'react';
import dynamic from 'next/dynamic';

function SdkComponent() {
  useEffect(() => {
    const initializeSdk = async () => {
      const { loadSdk } = await import('@facephi/sdk-loader');
      const apiKey = process.env.NEXT_PUBLIC_API_KEY || '';

      const sdkElement = await loadSdk({
        apiKey,
        containerId: 'sdk-container',
      });

      if (sdkElement) {
        sdkElement.addEventListener('emitIDVIntegration', (event) => {
          console.log('emitIDVIntegration:', event);
        });
      }
    };

    initializeSdk();
  }, []);

  return (
    <main>
      <section>
        <div id="sdk-container" />
      </section>
    </main>
  );
}

// Disable SSR for this component
export default dynamic(() => Promise.resolve(SdkComponent), {
  ssr: false,
});
```

{% endcode %}

{% hint style="info" %}
Use `dynamic` with `ssr: false` to ensure the SDK Loader only runs on the client.
{% endhint %}

## Styles

Add styles in your global CSS or in CSS modules:

{% code title="styles/globals.css" %}

```css
/* styles/globals.css */
#sdk-container {
  min-height: 400px;
  width: 100%;
}
```

{% endcode %}

For advanced styling options, see the [SDK Provider Customization documentation](/docs.facephi-en/sdks/sdk-web/personalizacion.md).

## Known issues

### Hydration error (hydration mismatch)

{% stepper %}
{% step %}

### Make sure to initialize on the client only

The SDK is only initialized on the client.
{% endstep %}

{% step %}

### Verify that the container exists

The container element exists before calling `loadSdk()`.
{% endstep %}

{% step %}

### Use the appropriate Next.js tools

Use the directive `'use client'` (App Router) or `dynamic` with `ssr: false` (Pages Router).
{% endstep %}
{% endstepper %}

### Module not found

{% stepper %}
{% step %}

### Check .npmrc

The file `.npmrc` is configured correctly.
{% endstep %}

{% step %}

### Verify installation

The package `@facephi/sdk-loader` is installed.
{% endstep %}

{% step %}

### Use dynamic import

Use dynamic import in the Pages Router approach.
{% endstep %}
{% endstepper %}

## Next steps

* [**SDK Configuration**](/docs.facephi-en/products/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/sdk-loader-idv/configuracion-del-sdk.md): Learn about all available configuration options
* [**SDK Web Components**](/docs.facephi-en/sdks/sdk-web/componentes.md): Explore the available widgets and their properties