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

# Nextjs

Next.js é um framework de React para criar aplicações web modernas com recursos como renderização no servidor (SSR), geração de sites estáticos (SSG) e renderização híbrida. Este guia explica como integrar o SDK Loader em aplicações Next.js.

{% hint style="warning" %}
Como o SDK Loader usa APIs do navegador (manipulação do DOM, carregamento dinâmico de scripts), ele deve ser executado **somente no lado do cliente**. O Next.js oferece várias formas de fazer isso, dependendo da sua abordagem de roteamento.
{% endhint %}

## Configuração do ambiente

Crie um arquivo `.env` na raiz do seu projeto:

```bash
NEXT_PUBLIC_API_KEY=YOUR_API_KEY
```

{% hint style="warning" %}
As variáveis com o prefixo `NEXT_PUBLIC_` são expostas ao navegador.
{% endhint %}

## App Router (Next.js 16+)

Para o App Router, use a diretiva `'use client'` para garantir que o componente seja executado no cliente.

### Exemplo: 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" %}
A diretiva `'use client'` é necessária porque o SDK Loader usa APIs do navegador.
{% endhint %}

## Pages Router (Next.js 16+)

Para o Pages Router, use `next/dynamic` com `ssr: false` para desativar a renderização no servidor do componente do SDK.

### Exemplo: 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` com `ssr: false` garante que o SDK Loader seja executado somente no cliente.
{% endhint %}

## Estilos

Adicione estilos no seu CSS global ou em módulos CSS:

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

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

{% endcode %}

Para opções avançadas de estilo, consulte a [documentação de Personalização do SDK Provider](/docs.facephi-pt-br/sdks/sdk-web/personalizacion.md).

## Problemas conhecidos

### Erro de hidratação (hydration mismatch)

{% stepper %}
{% step %}

### Certifique-se de inicializar somente no cliente

O SDK só é inicializado no cliente.
{% endstep %}

{% step %}

### Verifique se o contêiner existe

O elemento contêiner existe antes de chamar `loadSdk()`.
{% endstep %}

{% step %}

### Use as ferramentas adequadas do Next.js

Use a diretiva `'use client'` (App Router) ou `dynamic` com `ssr: false` (Pages Router).
{% endstep %}
{% endstepper %}

### Módulo não encontrado

{% stepper %}
{% step %}

### Verifique o .npmrc

O arquivo `.npmrc` esteja configurado corretamente.
{% endstep %}

{% step %}

### Verifique a instalação

O pacote `@facephi/sdk-loader` esteja instalado.
{% endstep %}

{% step %}

### Use importação dinâmica

Use importação dinâmica na abordagem com Pages Router.
{% endstep %}
{% endstepper %}

## Próximos passos

* [**Configuração do SDK**](/docs.facephi-pt-br/produtos/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/sdk-loader-idv/configuracion-del-sdk.md): Conheça todas as opções de configuração disponíveis
* [**Web Components do SDK**](/docs.facephi-pt-br/sdks/sdk-web/componentes.md): Explore os widgets disponíveis e suas propriedades