nuxt / nuxt/content

Prefer zod v4's native toJSONSchema() — make the zod-to-json-schema import lazy so v4 consumers don't need it

Open
#3,825 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
3.7k
Forks
746
Avg merge
1d 16h
Merged PRs (30d)
3

Description

Context

Nuxt Content 3.15.2 already ships a native zod v4 schema path: dist/chunks/zod4.mjs builds the JSON Schema via zod v4's built-in z.toJSONSchema(schema, { target: "draft-7", ... }) (with a small date/$content override). The vendor is detected per schema (dist/module.mjs:2334schema.def ? "zod4" : "zod3").

Problem

Despite the native v4 path, dist/module.mjs:50 statically imports the v3-era converter at module top level:

import { zodToJsonSchema, ignoreOverride } from "zod-to-json-schema";

and dependencies still pin the v3 line (zod ^3.25.76, zod-to-json-schema ^3.25.2).

Consequences for consumers that standardize on zod v4 (stable since 4.0):

  • Because the import is static, zod-to-json-schema must be resolvable in the consuming app's tree for the module to load at all — even when every collection schema is zod v4 and the native toJSONSchema() path is the one actually used.
  • Docus-based apps therefore must declare both zod and zod-to-json-schema purely to satisfy Nuxt Content's module load; nuxt prepare fails without them (a recurring trap — see the comment in geoql/v-maplibre's pnpm-workspace.yaml).
  • Zod v4 itself makes zod-to-json-schema obsolete for this use case: z.toJSONSchema() is built in.
Suggestion
  1. Make the zod-to-json-schema import lazy — dynamic-import it inside the zod3 toJSONSchema path only (the zod4 path already uses the native API), so v4-only consumers never need the package in their tree.
  2. Widen the zod dependency to include v4 (>=3.25.0 <5), and move zod/zod-to-json-schema to (optional) peerDependencies so the version the app actually uses is respected.

Happy to open a PR if this direction is welcome.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with dist/module.mjs:50 and the schema vendor detection around dist/module.mjs:2334, then compare the zod3 and zod4 implementations in dist/chunks/zod4.mjs. Verify the dependency declarations for zod and zod-to-json-schema. Done means zod4-only consumers can load the module without zod-to-json-schema while the zod3 path still works.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.