Problematiche con Server Side Rendering

[valeriocomo]

Cosa

Provando l'utilizzo del kit all'interno di una applicazione basata su Payload CMS (v3, basato su NextJS) si riscontrano problemi di Server Side Rendering (SSR). Occorre indagare come si comporta il framework all'interno di un contesto di compilazione SSR.

Considerando anche l'ampia adozione del framework Next.js, aggiungere un esempio di utilizzo sarebbe molto utile.

Perché

Il contesto SSR è molto utilizzato anche in framework come Nuxt basato su Vue. Inoltre l'esempio NextJS ci permette oltre ad avere un esempio di uno dei framework più utilizzati anche un ambiente dove testare il funzionamento del kit in questi contesti.

Contesto

Riporto alcuni stacktrace

Altro

Da Claude otteniamo queste informazioni

In Payload CMS (v3, Next.js-based) puoi usare Web Components ma con alcune limitazioni dovute al rendering server-side.
Approccio consigliato

1. Wrappa il Web Component in un Client Component React

Payload usa Next.js App Router, quindi devi isolare i Web Components in un file con 'use client':

// src/components/MyWebComponent.tsx
'use client'
import { useEffect, useRef } from 'react'
// Import del WC (side-effect only)
import 'my-web-component-lib'
export function MyWebComponent({ value }: { value: string }) {
  const ref = useRef<HTMLElement>(null)
  useEffect(() => {
    if (ref.current) {
      // Imposta proprietà non-string tramite ref (non attributi HTML)
      (ref.current as any).complexProp = { foo: 'bar' }
    }
  }, [])
  return <my-web-component ref={ref} value={value} />
}

2. Aggiungi le type declarations se necessario

// src/types/web-components.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    'my-web-component': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & { value?: string },
      HTMLElement
    >
  }
}

3. Registra il componente nell'import map di Payload

Se il componente va nell'admin UI, aggiungilo alla collezione e poi rigenera:

bun run generate:importmap

⚠️ Limitazioni da tenere a mente:

I Web Components non funzionano in SSR — assicurati che il rendering avvenga solo client-side (usa useEffect o dynamic con ssr: false)

Per componenti Payload custom (field UI, views), usa dynamic:

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

Le proprietà complesse (oggetti, array) vanno passate tramite ref, non come attributi HTML