> 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/productos/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/sdk-loader-idv/integrations/nextjs.md).

# Nextjs

Next.js es un framework de React para crear aplicaciones web modernas con funciones como renderizado en servidor (SSR), generación de sitios estáticos (SSG) y renderizado híbrido. Esta guía explica cómo integrar el SDK Loader en aplicaciones Next.js.

{% hint style="warning" %}
Dado que el SDK Loader utiliza APIs del navegador (manipulación del DOM, carga dinámica de scripts), debe ejecutarse **solo en el lado del cliente**. Next.js ofrece varias formas de hacerlo según tu enfoque de enrutamiento.
{% endhint %}

## Configuración del entorno

Crea un archivo `.env` en la raíz de tu proyecto:

```bash
NEXT_PUBLIC_API_KEY=YOUR_API_KEY
```

{% hint style="warning" %}
Las variables con el prefijo `NEXT_PUBLIC_` se exponen al navegador.
{% endhint %}

## App Router (Next.js 16+)

Para el App Router, usa la directiva `'use client'` para asegurarte de que el componente se ejecute en el cliente.

### Ejemplo: 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" %}
La directiva `'use client'` es necesaria porque el SDK Loader utiliza APIs del navegador.
{% endhint %}

## Pages Router (Next.js 16+)

Para el Pages Router, usa `next/dynamic` con `ssr: false` para desactivar el renderizado en servidor del componente del SDK.

### Ejemplo: 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>
  );
}

// Desactivar SSR para este componente
export default dynamic(() => Promise.resolve(SdkComponent), {
  ssr: false,
});
```

{% endcode %}

{% hint style="info" %}
Usar `dynamic` con `ssr: false` garantiza que el SDK Loader solo se ejecute en el cliente.
{% endhint %}

## Estilos

Añade estilos en tu CSS global o en módulos CSS:

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

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

{% endcode %}

Para opciones de estilo avanzadas, consulta la [documentación de personalización del SDK Provider](/sdks/sdk-web/personalizacion.md).

## Problemas conocidos

### Error de hidratación (hydration mismatch)

{% stepper %}
{% step %}

### Asegúrate de inicializar solo en el cliente

El SDK solo se inicializa en el cliente.
{% endstep %}

{% step %}

### Verifica que el contenedor exista

El elemento contenedor existe antes de llamar a `loadSdk()`.
{% endstep %}

{% step %}

### Usa las herramientas de Next.js adecuadas

Usa la directiva `'use client'` (App Router) o `dynamic` con `ssr: false` (Pages Router).
{% endstep %}
{% endstepper %}

### Módulo no encontrado

{% stepper %}
{% step %}

### Revisa .npmrc

El archivo `.npmrc` esté configurado correctamente.
{% endstep %}

{% step %}

### Verifica instalación

El paquete `@facephi/sdk-loader` esté instalado.
{% endstep %}

{% step %}

### Usa importación dinámica

Usa importación dinámica en el enfoque con Pages Router.
{% endstep %}
{% endstepper %}

## Siguientes pasos

* [**Configuración del SDK**](/productos/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/sdk-loader-idv/configuracion-del-sdk.md): Conoce todas las opciones de configuración disponibles
* [**Web Components del SDK**](/sdks/sdk-web/componentes.md): Explora los widgets disponibles y sus propiedades