Skip to content

perf: avoid bundling validators for lightweight SDK imports - #349

Merged
benbrandt merged 1 commit into
mainfrom
perf/tree-shake-protocol-helpers
Nov 17, 2026
Merged

benbrandt merged 1 commit into
mainfrom
perf/tree-shake-protocol-helpers

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Importing PROTOCOL_VERSION from the stable v1 entrypoint used to pull in nearly the same JavaScript as importing client. The entrypoint also initialized the protocol bindings and their Zod validators. This separates app bindings, method tables, and lightweight helpers into modules that bundlers can drop independently, and marks the package as side-effect-free.

Separately, the npm package no longer ships four internal zod.gen.d.ts files that none of the public declarations reference. All runtime validators still ship, as do the NES validator declarations exposed by experimental/nes.

Size impact

Single-export browser bundles, esbuild 0.28.2, minified ESM, dependencies included:

Import Before After
v1 PROTOCOL_VERSION 142.9 kB 39 B
v1 methods 142.9 kB 1.7 kB
v1 ndJsonStream 145.8 kB 4.2 kB
v1 client 142.9 kB 141.7 kB
v2 stable client 216.6 kB 163.1 kB

The npm tarball goes from 867 kB to 661 kB (9.80 MB to 4.90 MB unpacked). The full v1 client still needs wire validation; the largest bundle savings are for consumers of individual helpers.

Compatibility and verification

  • The export map is unchanged. Compared the emitted TypeScript declarations for every exported name on all 11 typed entrypoints against the base commit: no public API changes.
  • Typechecked all 11 entrypoints from the packed tarball under both NodeNext and Bundler with skipLibCheck: false. Also ran a client–agent initialize round trip from the tarball.
  • npm run check passed, including all 668 tests. package:check now bundles representative public imports for all four protocol entrypoints and fails if a lightweight import starts including Zod or a client pulls in another lane’s validators.

Separate the app bindings and method tables so lightweight SDK imports do not pull in runtime validation. Omit unused validator declarations from the tarball and check representative consumer bundles in CI.
@benbrandt
benbrandt merged commit 1bdba77 into main Nov 17, 2026
6 checks passed
@benbrandt
benbrandt deleted the perf/tree-shake-protocol-helpers branch November 17, 2026 22:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant