Skip to content

Commit 6f3b518

Browse files
colinhackscolinhacks
authored
v4: Doc updates for release (#4409)
* v4 release updates * Tweak
1 parent 71264f7 commit 6f3b518

File tree

14 files changed

+130
-148
lines changed

14 files changed

+130
-148
lines changed

‎.github/workflows/release-beta.yaml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ jobs:
3131
- name: Authenticate with npm
3232
run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
3333

34-
- id: publish
35-
name: Publish to NPM
36-
run: |
37-
pnpm run pub:beta
34+
# - id: publish
35+
# name: Publish to NPM
36+
# run: |
37+
# pnpm run pub:beta

‎.github/workflows/release.yml

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -30,24 +30,25 @@ jobs:
3030
run: |
3131
pnpm install
3232
33-
# - id: publish
34-
# name: Publish to NPM
35-
# uses: JS-DevTools/npm-publish@v3
36-
# with:
37-
# token: ${{ secrets.NPM_TOKEN }}
38-
# dry-run: false
39-
# provenance: true
33+
- id: publish
34+
name: Publish to NPM
35+
uses: JS-DevTools/npm-publish@v3
36+
with:
37+
token: ${{ secrets.NPM_TOKEN }}
38+
dry-run: true
39+
provenance: true
40+
package: ./packages/zod
4041

41-
# - name: Post-publish
42-
# if: steps.publish.outputs.type != 'none'
43-
# run: |
44-
# echo "Published ${{ steps.publish.outputs.type }} version: ${{ steps.publish.outputs.version }}"
42+
- name: Post-publish
43+
if: steps.publish.outputs.type != 'none'
44+
run: |
45+
echo "Published ${{ steps.publish.outputs.type }} version: ${{ steps.publish.outputs.version }}"
4546
46-
# - name: Publish skipped
47-
# if: steps.publish.outputs.type == 'none'
48-
# run: |
49-
# echo "Version in package.json has not changed. Skipping."
50-
# exit 0
47+
- name: Publish skipped
48+
if: steps.publish.outputs.type == 'none'
49+
run: |
50+
echo "Version in package.json has not changed. Skipping."
51+
exit 0
5152
5253
# - name: Configure changelog
5354
# if: steps.publish.outputs.type != 'none'

‎packages/bench/tsconfig.bench.json

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
"compilerOptions": {
44
"noEmit": true,
55
"extendedDiagnostics": true,
6-
"traceResolution": true
6+
"traceResolution": true,
7+
"customConditions": [],
8+
"skipDefaultLibCheck": true,
9+
"skipLibCheck": true,
710
}
811
}

‎packages/docs/app/layout.tsx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ export default function Layout({ children }: { children: ReactNode }) {
1818
<html lang="en" className={inter.className} suppressHydrationWarning>
1919
<body className="flex flex-col min-h-screen">
2020
<Banner id="zod4">
21-
These are the docs for Zod 4, which is currently in beta.<span>&nbsp;</span>
22-
<a className="underline" href="https://zod.dev">
23-
Go to Zod 3 docs 👉
21+
💎 Zod 4 is now stable! <span>&nbsp;</span>
22+
<a className="underline" href="/v4">
23+
Read the announcement.
2424
</a>
2525
</Banner>
2626
<InkeepBubble />

‎packages/docs/content/basics.mdx

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -45,28 +45,11 @@ const Player = z.object({
4545

4646
During this transition window:
4747

48-
1. Zod 4 will be considered 100% stable and production-ready
48+
1. Zod 4 is considered stable and production-ready
4949
2. The `"zod"` package will continue to be published in the `3.x.x` version range on npm. The `/v4` subpath will be added in the `zod@3.25` release.
5050
3. Zod 3 will continue to be exported from the package root (`"zod"`) as well as a new subpath (`"zod/v3"`). It will continue to receive bug fixes & stability improvements.
5151

52-
Why? Zod occupies a unique place in the ecosystem. Many libraries/frameworks in the ecosystem accept user-defined Zod schemas. This means their user-facing API is strongly coupled to Zod and its various classes/interfaces/utilities. For these libraries/frameworks, a breaking change to Zod necessarily causes a breaking change for their users. A Zod 3 `ZodType` is not assignable to a Zod 4 `ZodType`.
53-
54-
So why can't libraries just support v3 and v4 simultaneously? Unfortunately the limitations of peerDependencies (and inconsistencies between package managers) make it extremely difficult to elegantly support two major versions of one library simultaneously.
55-
56-
If I naively published `zod@4.0.0` to npm, the vast majority of the libraries in Zod's ecosystem would need to publish a new major version to properly support Zod 4. this includes some high-profile libraries like the `ai` SDK. it would trigger a "version bump avalanche" across the ecosystem and generally create a huge amount of frustration and work.
57-
58-
By co-publishing v3 and v4 together, we solve this problem. it provides a straightforward way to support Zod 3 and Zod 4 (including Zod Mini) simultaneously. they can continue defining a single peerDependency on `"zod"`; no need for more arcane solutions like npm aliases, optional peer dependencies, or a `"zod-compat"` package.
59-
60-
Existing projects will be able upgrade Zod to the latest minor version (`zod@3.25`) to get access to `"zod/v4"` and its many improvements. (During the beta period, they can use `zod@next`.) The can do this with confidence that there will be zero breakage.
61-
62-
Libraries will need to bump the minimum version of their `"zod"` peer dependency to `zod@^3.25.0`. They can then reference both Zod 3 and Zod 4 in their implementation:
63-
64-
```ts
65-
import * as z3 from "zod/v3"
66-
import * as z4 from "zod/v4"
67-
```
68-
69-
Later, once there's broad support for v4, we'll bump the major version on npm and start exporting Zod 4 from the package root, completing the transition. Zod 3 will remain available at `"zod/v3"` forever. While it may seem unorthodox, this is the only approach I'm aware of that enables a clean, incremental migration path for both Zod's users and the libraries in the broader ecosystem.
52+
For a complete breakdown of the subpath versioning strategy, see the [associated writeup](https://github.com/colinhacks/zod/issues/4371).
7053
</Accordion>
7154
</Accordions>
7255

‎packages/docs/content/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ import { Bronze } from '../components/bronze';
6565

6666
<div className="mt-5 font-gray-100 mx-auto text-center pt-12">
6767
<span className="">
68-
Zod 4 is now in beta! <a rel="noopener noreferrer" href="/v4" alt="zod 4 release notes">Click here</a> to read the release notes.
68+
Zod 4 is now stable! <a rel="noopener noreferrer" href="/v4" alt="zod 4 release notes">Click here</a> to read the release notes.
6969
</span>
7070
</div>
7171

‎packages/docs/content/library-authors.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Any library built on top of Zod should include `"zod"` in `"peerDependencies"`.
3333
}
3434
```
3535

36-
During development, you need to meet your own peer dependency requirement, to do so, add `"zod"` to your `"devDependencies"` as well. You'll need to use `zod@next` until `zod@3.25.0` is stably released.
36+
During development, you need to meet your own peer dependency requirement, to do so, add `"zod"` to your `"devDependencies"` as well.
3737

3838
```ts
3939
// package.json
@@ -42,7 +42,7 @@ During development, you need to meet your own peer dependency requirement, to do
4242
"zod": "^3.25.0"
4343
},
4444
"devDependencies": {
45-
"zod": "next"
45+
"zod": "^3.25.0"
4646
}
4747
}
4848
```

‎packages/docs/content/meta.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"root": true,
33
"pages": [
4-
"---Beta---",
4+
"---Zod 4---",
55
"v4/index",
66
"v4/changelog",
77
"---Documentation---",

‎packages/docs/content/v4/changelog.mdx

Lines changed: 13 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,31 @@ title: Migration guide
55
import { Callout } from "fumadocs-ui/components/callout";
66
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
77

8-
> To learn more about the performance enhancements and new features of Zod 4, read the [introductory post](/v4).
8+
> This migration guide aims to list the breaking changes in Zod 4 in order of highest to lowest impact. To learn more about the performance enhancements and new features of Zod 4, read the [introductory post](/v4).
99
10-
To give the ecosystem time to migrate, Zod 4 will initially be published alongside `zod@3.25.0`. It is consumable as a subpath import:
10+
To give the ecosystem time to migrate, Zod 4 will initially be published alongside Zod v3.25. To use Zod 4, upgrade to `zod@3.25.0` or later:
1111

12-
```ts
13-
import { z } from "zod/v4";
1412
```
15-
16-
This migration guide aims to list the breaking changes in Zod 4 in order of highest to lowest impact. Every effort was made to prevent breaking changes, but some are unavoidable.
17-
18-
<Callout>
19-
**Note** — Zod 3 exported a large number of undocumented quasi-internal utility types and functions that are not considered part of the public API. Changes to those are not documented here.
20-
</Callout>
21-
22-
To install the beta:
23-
24-
```
25-
npm upgrade zod@next
13+
npm upgrade zod@^3.25.0
2614
```
2715

28-
To start using Zod 4, import it from `zod/v4`:
16+
Zod 4 is available at the `"/v4"` subpath:
2917

3018
```ts
3119
import { z } from "zod/v4";
3220
```
3321

22+
<Callout>
23+
**Note** — Zod 3 exported a number of undocumented quasi-internal utility types and functions that are not considered part of the public API. Changes to those are not documented here.
24+
</Callout>
25+
3426
## Error customization
3527

36-
This is perhaps the most visible of the removed APIs. Zod 4 standardizes the APIs for error customization under a single, unified `error` param.
28+
Zod 4 standardizes the APIs for error customization under a single, unified `error` param. Previously Zod's error customization APIs were fragmented and inconsistent. This is cleaned up in Zod 4.
3729

3830
### deprecates `message`
3931

40-
Replace `message` with `error`. The `message` parameter is still supported but deprecated.
32+
Replaces `message` with `error`. The `message` parameter is still supported but deprecated.
4133

4234
<Tabs groupId="error-message" items={["Zod 4", "Zod 3"]} persist>
4335
<Tab value="Zod 4">
@@ -80,7 +72,9 @@ z.string({
8072

8173
### drops `errorMap`
8274

83-
This is renamed to `error`. Error maps can also now return a string or `undefined` (which yields control to the next error map in the chain).
75+
This is renamed to `error`.
76+
77+
Error maps can also now return a plain `string` (instead of `{message: string}`). They can also return `undefined`, which tells Zod to yield control to the next error map in the chain.
8478

8579
<Tabs groupId="error-map" items={["Zod 4", "Zod 3"]} persist>
8680
<Tab value="Zod 4">

0 commit comments

Comments
 (0)