listkit

Contexto

listkit (@pibytelabs/listkit) nació para eliminar la repetición de construir, una y otra vez, las mismas vistas de lista CRUD: toolbar, tabla, tarjetas, búsqueda, filtros y paginación. Una sola configuración describe toda la vista.

Arquitectura

Monorepo pnpm con el paquete publicable en packages/listkit y un playground Vite para desarrollo. El código se organiza en adapters/ (memory, fetch, serverAction, dexie), components/, hooks/ (incluidos los router adapters), theme/ y types/. Se compila con tsup a ESM + CJS + .d.ts con subpath exports (/next, /react-router, /adapters, /server).

Stack y API

defineListConfig() describe columnas, tarjetas, filtros, acciones y theme. ListView recibe la config más data (en memoria) o un adapter (asíncrono):

import { ListView, serverActionAdapter } from "@pibytelabs/listkit";
 
const adapter = serverActionAdapter<Product>(async (query) => {
  const { rows, total } = await listProductsAction(query);
  return { data: rows, total };
});
 
<ListView config={productsConfig} adapter={adapter} />;

Características clave:

• Responsive por defecto (alterna tabla/tarjetas según viewport).
• Filtros avanzados (text, select, multi-select, date-range, number-range, boolean) validados con Zod y sincronizados a la URL.
• Ordenamiento de columnas, caché integrada (stale-while-revalidate) o inyección de TanStack Query.
• SSR con initialData + buildListQuery (entry @pibytelabs/listkit/server).
• Router adapters para Next.js, React Router o el navegador.

Retos técnicos

• Mantener compatibilidad con React Server Components: un entry /server sin contexto cliente para no romper el render de Server Components.
• Evitar mismatches de hidratación recomputando la query exacta en servidor con buildListQuery.
• Empaquetado dual ESM/CJS con presupuestos de tamaño (size-limit) y validación de publicación (publint).

Resultado

Una librería tipada y reutilizable (MIT) que ya alimenta listas administrativas en proyectos reales como Agates From Mexico e Increscendo. El release está automatizado con Changesets. Código en GitHub.