Problemas frecuentes

Formato bitácora: síntoma → causa → solución.

La tabla se ve "rota": sin bordes, sin espaciados, botones pegados

Causa: Tailwind no está escaneando las clases de la librería.

Solución: añade en globals.css: @source "../node_modules/@fesa/components/src"; y reinicia el dev server.

Zebra, hover o fila seleccionada invisibles

Causa: faltan los tokens --color-background, --color-muted o --color-primary en el @theme de la app.

Solución: define el bloque @theme inline estándar de shadcn v4 (mapea --color-muted: var(--muted), etc.).

Export/copiar/imprimir sacan celdas vacías

Causa: columnas sin accessorKey — la librería no sabe de dónde sacar el valor plano.

Solución: añade accessorKey a cada columna de datos.

Cambié un filtro externo y la tabla busca con el valor anterior

Causa: el filtro solo vive en useState; el fetchFn corre antes del re-render y lee el closure viejo.

Solución: patrón estado + ref (receta): actualiza la ref, luego el estado, luego resetAndRefetch().

Tras crear/editar/borrar, la tabla no refleja el cambio

Causa: la mutación solo hace router.refresh(); con paginación en servidor eso no toca los datos que la tabla ya cargó.

Solución: tableRef.current?.silentRefetch() (+ router.refresh() únicamente para stats server-rendered).

Dos tablas en la misma página se pisan la paginación

Causa: ambas escriben ?page= sin prefijo.

Solución: paramPrefix distinto por tabla, también en la view (guía).

La URL se reescribe "sola" o pierde parámetros

Causa: la tabla tiene dos escritores de URL — useTableSearchParams (o useSmartTable) y syncSearchParams: true a la vez.

Solución: usa uno u otro por tabla, nunca ambos.

bun install no trae mi último cambio de la librería

Causa: bun cachea la resolución del repo git y a veces no mueve el commit aunque muevas el tag.

Solución:

bun pm cache rm
# borra la(s) línea(s) @fesa/components/datatable del bun.lock
rm -rf node_modules/@fesa
bun install

En el VPS el install falla resolviendo @fesa/components/datatable

Causa: el servidor no puede leer el repo privado por SSH.

Solución: deploy key read-only en GitHub → fesa-components → Settings → Deploy keys. El VPS fesa.prod ya la tiene (~/.ssh/fesa_datatable_deploy). Verifica con git ls-remote [email protected]:AdanSerrano/fesa-components.git HEAD.

Typecheck de la app falla con tipos duplicados de React (VoidOrUndefinedOnly…)

Causa: estás usando dependencia file:../fesa-components local y el node_modules de la lib duplica @types/react.

Solución: para iterar en local borra fesa-components/node_modules/@types y react*; para consumo normal usa la dependencia git (instala limpia y el problema no existe).

La virtualización no virtualiza (o descuadra las filas)

Causa: falta style.maxHeight (el contenedor no scrollea) o las filas no miden el rowHeight declarado.

Solución: pon maxHeight, ajusta rowHeight a la densidad real (48px en "default"), y no combines con filas expandibles.

El toast de error tarda ~10 segundos en aparecer con la base caída

Causa: no es la tabla — es el pool_timeout de Prisma esperando conexión antes de rendirse.

Solución: es el comportamiento esperado; el mensaje que llega al toast es el del servidor. Si quieres fallar antes, baja pool_timeout en la DATABASE_URL.

La selección desaparece al buscar

Causa: es a propósito — una búsqueda nueva limpia la selección para que una acción masiva nunca opere sobre filas que ya no coinciden con el filtro.

Solución: ninguna; es el contrato de la selección cross-page.