CodeVetter · Repo Unpack · System map
colinhacks/zod
The repository is a Nub-managed ESM monorepo whose principal deliverables are the `zod` and `@zod/mini` packages. Zod v4 is layered into a shared core, a fluent classic facade, and a functional mini facade; v3 remains published through a separate compatibility entrypoint. Runtime validation is entirely in-process, while the repository also contains a statically generated Next.js documentation application and maintenance scripts that access GitHub, npm, JSR, and the ISO currency source. Publishing is a manually dispatched, approval-gated GitHub Actions workflow rather than an automatic deployment from `main`.
- The root workspace is private, ESM-only, pinned to Nub 0.8.3, and discovers packages through `packages/*`; root scripts build `zod` and `@zod/mini`, run Vitest, check formatting, linting, circular dependencies, version consistency, comments, and release lockstep.
- The published `zod` package exposes root, mini, compile, locales, v3, v4, v4-mini, v4/mini, v4/core, and locale wildcard subpaths for source, ESM, CommonJS, and declarations.
- The root `zod` entrypoint re-exports the v4 classic facade, while separate entrypoints route `zod/mini` to the v4 mini facade and `zod/v3` to the legacy implementation.
- The v4 runtime boundary is explicit: `core/index.ts` exports constructors, parsers, schemas, checks, registries, compilation, and JSON Schema machinery; classic and mini compose those primitives into distinct public APIs.
- Schema instances are trait-composed objects created through `$constructor`; their internal definitions, parse functions, traits, structural metadata, and deferred initialization live under a non-enumerable `_zod` property.
- Runtime state is process-local rather than database-backed: global configuration and metadata registries are shared through `globalThis`, while parse-cycle state uses WeakMaps keyed by schemas, objects, and parse contexts.
- The documentation application is a Next.js 15 and React 19 workspace using Fumadocs, Tailwind, Vercel Analytics, and Inkeep search/chat; its content is compiled from MDX collections.
- Auxiliary workspaces separate concerns: `packages/bench` benchmarks competing validators, `packages/integration` type-checks Drizzle and AI SDK fixtures, `packages/resolution` verifies built module resolution, and `packages/treeshake` measures bundler behavior.
- The normal build uses zshy to emit the packages and declarations, while package exports select raw TypeScript only under the private `@zod/source` condition used by repository development and tests.
- Production documentation deployment is shaped for Vercel: the install command bootstraps the pinned Nub release, installs the monorepo lockfile, and then runs the repository build.
- Release deployment is manual and approval-gated: the workflow tests, builds, validates package resolution, publishes both packages to npm and JSR with provenance, creates a GitHub release, and verifies the two packages remain version-aligned.