Ricardo Tapia
/
OSSProducción

listkit

Librería React para vistas de lista estandarizadas: 10 subpath exports tree-shakeables, filtros avanzados validados con Zod y exportación CSV byte-idéntica.

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 y se distribuye en 10 subpath exports tree-shakeables (/next, /react-router, /adapters, /server, entre otros), de modo que cada consumidor importa solo lo que usa.

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.
  • Exportación CSV con paridad byte-idéntica verificada en CI contra MongoDB y PostgreSQL reales.
  • i18n EN/ES integrado.
  • 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), actualmente en v4.7.0, que ya alimenta listas administrativas en proyectos reales como Agates From Mexico e Increscendo. Publicada en npm con releases automatizados vía release-please en CI. Código en GitHub.

¿Hablamos?