Tamanho do bundle e formatos de módulo

O SDK é distribuído com um build CommonJS e um build ESM, e mantém as suas duas dependências pesadas, Zod e socket.io-client, fora do grafo de importação até que sejam usadas. Um projeto que chama um único método, deixa a validação desativada e nunca abre um socket carrega cerca de 49 kB minificados (10.9 kB com gzip), em vez de 706 kB (141 kB com gzip) na 1.0.158.

O que vem no pacote

Campo	Valor	Usado por
main	dist/index.js	Node e qualquer consumidor CommonJS
module	esm/index.js	Bundlers (webpack, Vite, Rollup, esbuild)
types	dist/index.d.ts	TypeScript
sideEffects	false	Bundlers, para descartar módulos não utilizados
exports	., ./types, ./dist/*, ./esm/*, ./package.json	Node e bundlers que leem o mapa exports

O mapa exports direciona import para o build ESM e require para o build CommonJS, tanto na raiz quanto em oneentry/types. Ele também expõe ./dist/* e ./esm/*, de modo que as importações profundas existentes (oneentry/dist/<module>/<module>Interfaces e as demais) continuam sendo resolvidas, e a sua configuração atual não precisa mudar.

sideEffects: false informa ao bundler que importar um módulo do SDK não tem efeitos colaterais. É isso que faz o tree-shaking funcionar: os módulos que você não usa são removidos do resultado.

O Zod só é carregado quando a validação é executada

A validação de respostas vem desativada por padrão. Os esquemas e os helpers de validação são carregados sob demanda, na primeira vez em que uma resposta precisa ser validada. (As versões anteriores importavam os esquemas estaticamente em todos os módulos, o que colocava o Zod em todos os bundles mesmo quando nada era validado.)

• Com validation.enabled: false (o padrão), o Zod e os esquemas por módulo (~400 kB) ficam em chunks que nunca são solicitados.
• Com validation.enabled: true, a validação funciona como antes; os esquemas são buscados na primeira vez em que são necessários.
• No Node, require('oneentry') não carrega mais o Zod na inicialização.

Esses números pressupõem um bundler com code splitting, o padrão no webpack, no Vite e no Rollup. Um bundle forçado em um único arquivo também diminui, mas só até ~447 kB, porque o Zod é incluído mesmo sem nunca ser executado.

A API pública é a mesma. O helper interno _validateResponse agora é async, o que só importa se você estendeu por conta própria as classes base do SDK.

O socket.io só é carregado quando você abre um socket

WS.connect() continua síncrono e retorna um Socket do socket.io, mas o socket.io-client (~43 kB) é importado na primeira vez em que connect() é chamado.

Até que o chunk seja carregado, o objeto retornado enfileira todas as chamadas que você faz nele (on, emit, disconnect) e as repete no socket real no mesmo tick em que o socket é criado, antes que a conexão possa entregar qualquer coisa. Nenhum evento é perdido:

// 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));

Ler o estado da conexão cedo continua sendo preciso, porque um socket recém-criado também não está conectado: id é undefined e connected é false, como antes.

A única diferença: um método que precisa retornar algo (por exemplo listeners()) não consegue responder antes de o chunk chegar, e objetos aninhados como socket.io só ficam acessíveis depois que ele é carregado. Registrar handlers e emitir eventos, o uso normal, não são afetados.

Tamanho do bundle em resumo

Cenário	Minificado	Gzip
Antes (1.0.158, todos os consumidores)	706 kB	141 kB
Validação desativada, sem socket	49 kB	10.9 kB
Validação desativada, socket aberto	~92 kB	~24 kB
Bundle em um único arquivo, sem code splitting	~447 kB	~94 kB

Medições na 1.0.173 (1.0.158 na primeira linha) com esbuild 0.24.2: saída ESM, --bundle --splitting --minify, plataforma browser, um app que chama Pages.getPageByUrl uma vez (mais WS.connect() na linha do socket); gzip no nível 9. Outros bundlers dão números um pouco diferentes.

Obtendo o menor build

• Deixe a validação desativada em produção. Ative-a durante o desenvolvimento para detectar inconsistências nos dados e desative-a de novo, para que os esquemas fiquem fora do código carregado.
• Deixe o seu bundler dividir o código. O code splitting vem ativado por padrão no webpack, no Vite e no Rollup. Desativá-lo incorpora os chunks carregados sob demanda e devolve a maior parte da economia.
• Importe tipos com import type. As importações de tipo são removidas na compilação; veja Importação de tipos.
• Desestruture apenas os módulos que você usa. Com sideEffects: false e o build ESM, os módulos não utilizados são removidos do resultado.

---

Relacionados

• Importação de tipos: os pontos de entrada oneentry e oneentry/types
• Validação de respostas da API: como ativar e configurar a validação com Zod
• Módulo WS: abrindo uma conexão em tempo real

---