Skip to main content

Using the React SDK with server-side rendering frameworks

The kapa.ai React SDK is a client-side only library and does not support server-side rendering (SSR). The SDK relies on browser-specific dependencies like reCAPTCHA that must run in a browser environment.

When implementing the SDK in SSR frameworks, ensure that any component using the Kapa SDK only renders on the client side. This includes both the KapaProvider and any components that use the useChat hook.

Framework-specific implementation​

Astro and Astro Starlight​

Use the client:only directive on your component:

<YourKapaComponent client:only="react" />

Without this directive, you'll encounter module export errors during the build process.

Next.js​

Use dynamic imports with SSR disabled:

const YourKapaComponent = dynamic(
  () => import('./YourKapaComponent'),
  { ssr: false }
)

Other SSR frameworks​

Each framework has its own approach to client-only rendering:

  • Gatsby: Conditional rendering after component mount
  • Remix: Client-only routes or lazy loading
  • SvelteKit: Client-side component loading

Consult your framework's documentation for the appropriate client-only rendering method.