Tamaño del bundle y formatos de módulo

El SDK se distribuye con una compilación CommonJS y otra ESM, y mantiene sus dos dependencias pesadas, Zod y socket.io-client, fuera del grafo de importaciones hasta que se usan. Un proyecto que llama a un solo método, deja la validación desactivada y nunca abre un socket carga unos 49 kB minificados (10.9 kB con gzip), frente a 706 kB (141 kB con gzip) en la 1.0.158.

Qué incluye el paquete

Campo	Valor	Lo usa
main	dist/index.js	Node y cualquier consumidor CommonJS
module	esm/index.js	Bundlers (webpack, Vite, Rollup, esbuild)
types	dist/index.d.ts	TypeScript
sideEffects	false	Bundlers, para descartar los módulos no utilizados
exports	., ./types, ./dist/*, ./esm/*, ./package.json	Node y los bundlers que leen el mapa de exports

El mapa exports dirige import a la compilación ESM y require a la compilación CommonJS, tanto para la raíz como para oneentry/types. También expone ./dist/* y ./esm/*, de modo que las importaciones profundas existentes (oneentry/dist/<module>/<module>Interfaces y las demás) se siguen resolviendo y no necesitas cambiar tu configuración actual.

sideEffects: false indica al bundler que importar un módulo del SDK no tiene efectos secundarios. Eso es lo que hace funcionar el tree-shaking: los módulos que no usas se eliminan del resultado.

Zod solo se carga cuando se ejecuta la validación

La validación de respuestas está desactivada por defecto. Los esquemas y las utilidades de validación se cargan bajo demanda, la primera vez que hay que validar una respuesta. (Las versiones anteriores importaban los esquemas de forma estática en cada módulo, lo que metía Zod en todos los bundles aunque no se validara nada).

• Con validation.enabled: false (el valor predeterminado), Zod y los esquemas de cada módulo (~400 kB) acaban en chunks que nunca se solicitan.
• Con validation.enabled: true, la validación funciona como antes; los esquemas se obtienen la primera vez que se necesitan.
• En Node, require('oneentry') ya no carga Zod al iniciar.

Estas cifras suponen un bundler que divide el código, el comportamiento predeterminado en webpack, Vite y Rollup. Un bundle forzado a un único archivo también se reduce, pero solo a ~447 kB, porque Zod se incluye en línea aunque nunca se ejecuta.

La API pública es la misma. La utilidad interna _validateResponse ahora es async, lo que solo importa si has extendido tú mismo las clases base del SDK.

socket.io solo se carga cuando abres un socket

WS.connect() sigue siendo síncrono y devuelve un Socket de socket.io, pero socket.io-client (~43 kB) se importa la primera vez que se llama a connect().

Hasta que se carga el chunk, el objeto devuelto pone en cola todas las llamadas que haces sobre él (on, emit, disconnect) y las reproduce sobre el socket real en el mismo tick en que se crea el socket, antes de que la conexión pueda entregar nada. No se pierde ningún evento:

// Nothing changes in normal use — handlers registered here always fire.
// Requires an access token: call AuthProvider.auth() first. With only auth.refreshToken
// in the config, make an authorized call (for example Users.getUser()) before connect()
// so the SDK refreshes the token.
const socket = WS.connect();

socket.on('connect', () => console.log('WebSocket connected'));
socket.on('my_event', (payload) => console.log(payload));

Leer el estado de la conexión antes de tiempo sigue siendo exacto, porque un socket recién creado tampoco está conectado: id es undefined y connected es false, como antes.

La única diferencia: un método que tiene que devolver algo (por ejemplo, listeners()) no puede responder antes de que llegue el chunk, y los objetos anidados como socket.io solo son accesibles después de que se cargue. Registrar manejadores y emitir eventos, el uso normal, no se ve afectado.

El tamaño del bundle de un vistazo

Escenario	Minificado	Gzip
Antes (1.0.158, todos los consumidores)	706 kB	141 kB
Validación desactivada, sin socket	49 kB	10.9 kB
Validación desactivada, con socket abierto	~92 kB	~24 kB
Bundle de un solo archivo, sin división de código	~447 kB	~94 kB

Medido en la 1.0.173 (la 1.0.158 en la primera fila) con esbuild 0.24.2: salida ESM, --bundle --splitting --minify, plataforma browser, una app que llama una vez a Pages.getPageByUrl (más WS.connect() en la fila del socket); gzip de nivel 9. Otros bundlers dan cifras algo distintas.

Cómo conseguir la compilación más pequeña

• Deja la validación desactivada en producción. Actívala durante el desarrollo para detectar incoherencias en los datos y vuelve a desactivarla, para que los esquemas queden fuera del código que se carga.
• Deja que tu bundler divida el código. La división de código está activada por defecto en webpack, Vite y Rollup. Desactivarla incluye los chunks diferidos y anula la mayor parte del ahorro.
• Importa los tipos con import type. Las importaciones de tipos se eliminan en tiempo de compilación; consulta Importación de tipos.
• Desestructura solo los módulos que uses. Con sideEffects: false y la compilación ESM, los módulos no utilizados se eliminan del resultado.

---

Relacionado

• Importar tipos: los puntos de entrada oneentry y oneentry/types
• Validación de respuestas de la API: cómo activar y configurar la validación con Zod
• Módulo WS: abrir una conexión en tiempo real

---