Walkthrough

Updated documentation: README reordered TOC, added contributor badges, new Caveats entry for "TypeError: example is not a function", replaced Node.js tsconfig guidance with ESM-run instructions, adjusted examples to use factory.build and simplified object construction; CHANGELOG added v25.5.3 with ESM/zod guidance.

Changes

Sequence Diagram(s)

The changes are documentation-only and do not modify runtime control flow; no sequence diagram is provided.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• Addressing potential zod@^4 augmentation issue #2832 — Similar README/CHANGELOG edits addressing Zod v4 and ESM/CJS guidance and caveats.
• Pure ESM distribution #2814 — Related to ESM distribution/packaging changes and documentation about running as pure ESM.

Suggested labels

prevention

Poem

I nibble docs with curious paws,
I hop through notes and tidy the laws,
.mts and "type":"module" in sight,
strict and skipLibCheck make things right,
A rabbit grins — the README's bright. 🐇✨

Pre-merge checks and finishing touches

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

@coderabbitai, the cause of the issue is described here: #2981 (comment)

#!/bin/bash
# Fetch the specific comment from issue #2981
gh api repos/RobinTail/express-zod-api/issues/comments/3360464495 --jq '.body'

@RobinTail, thank you for the clarification! I now understand the root cause:

The issue occurs when users run v25 (ESM-only) with CommonJS code. Since Express Zod API imports and patches Zod's ESM bundle with the .example() method, but user code compiled as CommonJS requires Zod's CJS bundle, they end up with two separate instances of Zod. The patched ESM instance has .example(), but the CJS instance used by the user's code does not.

This PR correctly addresses the issue by updating the documentation to emphasize ESM requirements, including:

• Setting "type": "module" in package.json
• Using .mts extension
• Configuring proper compilerOptions for ESM output

The documentation changes will help users properly configure their projects to use ESM, ensuring they use the same Zod instance that Express Zod API patches.

Learnt from: RobinTail
URL: https://github.com/RobinTail/express-zod-api/pull/2984

Timestamp: 2025-10-02T17:19:20.584Z
Learning: In express-zod-api v25 (ESM-only), the `.example()` method error occurs when user code runs as CommonJS. Express Zod API patches Zod's ESM bundle with `.example()`, but CommonJS code requires a separate CJS bundle instance that lacks this patch. Users must configure their projects for ESM (package.json "type": "module", .mts extension, or proper compilerOptions) to use the patched Zod instance.

coverage: 100.0%. remained the same
when pulling ef36a6b on issue-2981-force-esm
into 39cd60e on master.

@coderabbitai, compilerOptions do not make it ESM, only type in package.json or mts/mjs extension does. Alternative way is to run the cosumer's code using tsx or vite-node that use their own compilers.

@RobinTail, thank you for the correction! You're absolutely right—compilerOptions alone don't determine whether code runs as ESM. The module system is controlled by:

• "type": "module" in package.json, or
• Using .mts/.mjs file extensions, or
• Running with tools like tsx or vite-node that provide their own compilation

I've updated my understanding accordingly.

Learnt from: RobinTail
URL: https://github.com/RobinTail/express-zod-api/pull/2984

Timestamp: 2025-10-02T17:42:48.813Z
Learning: In express-zod-api v25 (ESM-only), the `.example()` method error occurs when user code runs as CommonJS. Express Zod API patches Zod's ESM bundle with `.example()`, but CommonJS code requires a separate CJS bundle instance that lacks this patch. Users must run their code as ESM by: (1) setting `"type": "module"` in package.json, (2) using `.mts` or `.mjs` file extensions, or (3) using tools like `tsx` or `vite-node` that provide their own ESM-compatible compilation.

Learnt from: RobinTail
PR: RobinTail/express-zod-api#0
File: :0-0
Timestamp: 2025-10-02T17:19:20.584Z
Learning: In express-zod-api v25 (ESM-only), the `.example()` method error occurs when user code runs as CommonJS. Express Zod API patches Zod's ESM bundle with `.example()`, but CommonJS code requires a separate CJS bundle instance that lacks this patch. Users must configure their projects for ESM (package.json "type": "module", .mts extension, or proper compilerOptions) to use the patched Zod instance.

Learnt from: RobinTail
PR: RobinTail/express-zod-api#0
File: :0-0
Timestamp: 2025-10-02T17:19:20.584Z
Learning: In express-zod-api v25 (ESM-only), the `.example()` method error occurs when user code runs as CommonJS. Express Zod API patches Zod's ESM bundle with `.example()`, but CommonJS code requires a separate CJS bundle instance that lacks this patch. Users must configure their projects for ESM (package.json "type": "module", .mts extension, or proper compilerOptions) to use the patched Zod instance.