Add section on Zod 4 to v6 migration guide

[matthewp]

Description (required)

Adds Zod 4 under the "Dependency Upgrades" section.

Mostly just refers to the Zod 4's own migration guide.

Related issues & labels (optional)

For Astro version: 6.x. See astro PR #14956.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/content-collections.mdx	Source changed, localizations will be marked as outdated.
en/guides/upgrade-to/v6.mdx	Localization changed, will be marked as complete.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	6b01550
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/693c574af64fd90008754306
😎 Deploy Preview	https://deploy-preview-12848--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sarah11918]

Thanks, @matthewp !

Also checking that none of these examples here where we describe using Zod for content collections look outdated to you? (This whole section on "Defining the collection schema" including the subsections for defining data types and collection references): https://deploy-preview-12322--astro-docs-2.netlify.app/en/guides/content-collections/#defining-datatypes-with-zod

We also do mention and show examples of Zod schemas on the actions page, but it's probably the two sections here about validation where we have text/examples that we should double check are still accurate for Zod 4: https://deploy-preview-12322--astro-docs-2.netlify.app/en/guides/actions/#using-validators-with-form-inputs

Lastly, even though Zod's migration guide shows everything, I would suspect there would be some changes that are common that most people would have to make to content collections schemas that are worth showing here, a way of focusing their attention on things that they'd very likely have to deal with. Can you suggest what some of those might be? If for example there were one or two things ONLY thing that will affect the majority of people, but maybe that's all they need to do, it would be much better for us to show those here. If it would be possible to help a number of people avoid needing to go to Zod's guide at all, then we really should do that.

[ArmandPhilippot]

In addition to what Sarah just said, I noticed another change in the implementation regarding the use of the image() helper:

-heroImage: image().optional(),
+heroImage: z.optional(image()),

Does this mean that image() is no longer chainable with Zod 4? Does this also apply to reference()? Since both are specific to Astro, we might need to say something about them in our upgrade guide.

[matthewp]

@sarah11918

Also checking that none of these examples here where we describe using Zod for content collections look outdated to you?

Yes, I wasn't sure if updating other docs was in scope for these PRs or not, since in the last one it was not. Happy to update other docs though, just tell me.

Lastly, even though Zod's migration guide shows everything, I would suspect there would be some changes that are common that most people would have to make to content collections schemas that are worth showing here, a way of focusing their attention on things that they'd very likely have to deal with. Can you suggest what some of those might be?

Not really, no. I can only say what was common in updating Astro itself, but I wouldn't presume that holds over to CC users. For example .default() was a bit of a problem for Astro but I don't know if users are going to need that a lot for CC (I wouldn't see a need for it personally). So I'd be afraid giving advice here would just be inaccurate. Perhaps when we have people upgrading it will reveal what's common?

[matthewp]

@ArmandPhilippot

Does this mean that image() is no longer chainable with Zod 4? Does this also apply to reference()? Since both are specific to Astro, we might need to say something about them in our upgrade guide.

It should still be chainable, I'll check to confirm.

[sarah11918]

Just noting that we're holding on this one as some aspects of the implementation PR might determine what kind of guidance is needed here!

[matthewp]

@sarah11918 Which aspects? So I can unblock if possible.

[sarah11918]

@matthewp We were waiting on whether or not reference() and image() were going to have to update re: the chaining question. (If so, we'd need to say that here.) But, it looks like that was a bug that was fixed, and we don't need to provide that specific guidance anymore!

[sarah11918]

Seeing #12866 and that some of our Action code samples had to update makes me think that mentioning some of Zod's changes ourself is probably helpful. Expecially if people have followed our code examples, and we are updating examples in docs, that's probably a good indication of what's common enough to include as some additional helpful content.

So, in the Actions guide, we saw our own examples update from z.string().email() and z.string.url() to just z.email() and z.url(). We could therefore include something like:

Many string() formats have been deprecated (e.g. email(), url()), and their APIs have been moved to the top-level z namespace. You may need to update how you validate form input for your Astro Actions.

Presumably the default()/prefault() shenanigans are similarly worth pointing out in particular that people may very well need to go see what to do there, but is there anything else?

[ArmandPhilippot]

I think what you mentioned could be the most commonly used. Except that, maybe customizing errors?

For people using Zod on the client (e.g. a form) and having implemented i18n, they probably customized the error messages because every errors were in English in Zod 3. The message property is replaced with error and the errorMap no longer exists. Now, Zod has built-in translations... but it seems we might not ship this (this feature is in zod/core).

And, yes, we should mention Actions schema in addition to content collections!

[matthewp]

Do I need to update the examples/docs in this PR to their proper v4 usage?

[sarah11918]

Hi @matthewp , sorry there hasn't been a lot of direct actionable instructions on this PR as Armand and I have kind of been discussing what might need to be said!

I have taken a quick look through all the content collections material we show and I think I only saw one stray z.string().url() but otherwise, our content collections/astro:content/loader API docs and (thanks to Armand) our Actions docs should all be updated.

So here's what you can do:

• on the content-collections.mdx page, update z.string().url() to the Zod4 z.url(). As far as I can tell, I think Armand and I have caught everything else in code samples.

• I will suggest here a short blurb reminding people to check their actions because common validation syntax like z.string().url() and z.string().email() have changed. Can you please write a little something similar about whatever the heck is going on with default() that people might need to know? ("similar" in the sense that you don't have to be the Zod 4 upgrade guide, but rather just pointing it out as something to look for in that guide because we expect this might affect a significant number of people?)

• It looks like Armand thinks pointing out something about translatable error messages might be a thing, too. If people will need to update their error messages as a result of this, please also add a "similar" point about that. Again, the goal is only to point people to the common things in that whole guide that we already know a lot of people will need to know, so we can help focus their attention to those common things.

I think that's all we'll do for now. As we notice people trying the beta and maybe struggling with the upgrade on certain things, we might later decide to add more specific guidance here.

[sarah11918]

(Note: I added a Zod link, but this PR might need to be updated to the v6 branch to have access to some of the most recent comment. I suspect that will fix any link issues!)

[matthewp]

It looks like Armand thinks pointing out something about translatable error messages might be a thing, too. If people will need to update their error messages as a result of this, please also add a "similar" point about that. Again, the goal is only to point people to the common things in that whole guide that we already know a lot of people will need to know, so we can help focus their attention to those common things.

I don't know anything about this, can you explain @ArmandPhilippot ?

[sarah11918]

@matthewp I think it might in fact be anyone creating custom error messages (and, translated ones are just a special case)? Hideoo commented that this section of the Zod guide might affect a significant number of people: https://zod.dev/v4/changelog#changes-error-map-precedence

Does that make sense/help? (Sorry, I'm not familiar with this myself, and am relying on y'all.)

[matthewp]

@sarah11918 I'm also not that familiar with this, which is partially why I've been hesitant to give too much direct advice on how to migrate Zod.

In the case of the link, that's done internally inside of Astro when it validates the schema. How a user can have custom error messages in their schema; I don't know the answer to that. I think it might not be possible any more, but I could be wrong.

[ArmandPhilippot]

Yeah, as Sarah said, it's not about repeating all Zod changes, but simply highlighting common use cases, and error customization could be one of them.

Maybe something like:

Zod has dropped support for a custom `errorsMap` which was useful to redefine or translate your error messages. Some other changes have been made to the way to customize the error messages, you might need to update your code:

```diff
-z.string().min(5, { message: "Too short." });
+z.string().min(5, { error: "Too short." });
```

[sarah11918]

That looks good, Armand!

[matthewp]

I took a pass at explaining the default() change, let me know what you think. Over-explanation?

[sarah11918]

@matthewp I think the default section looks great! I think between your suggestion and mine, that probably helps a lot of people get started with updating Zod and might alleviate a lot of support threads. 😄

If you're happy with the content now, including all the suggestions, I think this is good to go!

[sarah11918]

(Just resolved conflicts and updated branch)

[sarah11918]

I think this is good to go! Can update branch and merge any time!