Document new `ActionInputSchema` utility type #12647

mauriciabad · 2025-10-31T03:34:27Z

Description

Documentation for the new ActionInputSchema utility type I proposed in withastro/astro#14698

I put the latest version +1 patch in the <Since> component, but I don't know the exact version yet.

Feel free to change the text if is not clear :)

I also native Spanish, if you want me to translate it.

netlify · 2025-10-31T03:34:33Z

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`c23454c`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/691bdf8159903b0008853b6c
😎 Deploy Preview	https://deploy-preview-12647--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.

astrobot-houston · 2025-10-31T03:35:03Z

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/reference/modules/astro-actions.mdx	Source changed, localizations will be marked as outdated.

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.

sarah11918 · 2025-11-03T11:09:03Z

src/content/docs/en/reference/modules/astro-actions.mdx

+<Since v="5.15.4" />
+</p>
+
+A utility type that extracts the input's **zod schema type** from [an action handler](#defineaction). This can be useful if you need to reference an [action's validator]((#input-validator)) input type in your own type definitions.


Suggested change

A utility type that extracts the input's **zod schema type** from [an action handler](#defineaction). This can be useful if you need to reference an [action's validator]((#input-validator)) input type in your own type definitions.

A utility type that extracts the input's **zod schema type** from [an action handler](#defineaction). This can be useful if you need to reference an [action's validator](#input-validator) input type in your own type definitions.

fix link syntax

sarah11918 · 2025-11-12T16:25:52Z

Thanks for submitting this documentation with your feature @mauriciabad ! I will also ask @florian-lefebvre to check in on these docs after everything is resolved in the Astro feature PR to make sure what's here matches the decisions made over there!

florian-lefebvre

Confirming we keep the name so docs can be reviewed!

src/content/docs/en/reference/modules/astro-actions.mdx

Co-authored-by: Florian Lefebvre <[email protected]>

sarah11918

Thanks for submitting docs to go with your feature, @mauriciabad ! I'll probably also need @ArmandPhilippot to help me with wording here because this is not my area of expertise and I do think we need to adjust the text here to match the Astro docs style.

I've left some comments/questions!

src/content/docs/en/reference/modules/astro-actions.mdx

sarah11918 · 2025-11-17T16:12:39Z

src/content/docs/en/reference/modules/astro-actions.mdx

+
+A utility type that extracts the input's **zod schema type** from [an action handler](#defineaction). This can be useful if you need to reference an [action's validator](#input-validator) input type in your own type definitions.
+
+Even if the action [accepts `form`](#accept-property), `ActionInputSchema` lets you get the input type as `object` rather than [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData).


It feels like this wording needs checking against the wording at #accept-property (does that wording need any updating?) The docs for accept say:

When your action accepts form inputs, the z.object() validator will automatically parse FormData to a typed object. All Zod validators are supported to validate your inputs.

is this still happening automatically?

Does this happen in addition to you being able to get the input type as this new object?

Do we need a link up there to this new entry to mention this option?

It feels like maybe the link to FormData is best up there?

Just want to make sure that the docs are in sync with each other.

I don't think this means the accept docs is outdated. What happens when using accept: "form" is:

we define a Zod schema to validate the data

the action sends a FormData object

the validator converts that to a different object shape

ActionInputSchema can be used to retrieve the type of that different object shape

So basically, I'd say ActionInputSchema doesn't care about the input shape. All it's doing is extracting the type of the final object.

Actually this paragraph is not necessary because the returned type already documented above.
I added it thinking of possible doubts users would have, but it doesn't add any new info.

sarah11918 · 2025-11-17T16:21:18Z

src/content/docs/en/reference/modules/astro-actions.mdx

+
+Even if the action [accepts `form`](#accept-property), `ActionInputSchema` lets you get the input type as `object` rather than [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData).
+
+If the [`input` validator](#input-validator) is omitted, it returns `never`.


This says if input is not provided, "it" returns never. It's not clear to me what "it" is. (ActionInputSchema? Can it return never?) nor what never means in this context.

it means the return type of the ActionInputSchema generic type. and never means the never TS type

Yeah, this means that what we are trying to do will never happen, the type can't be resolved. In this context, if the input validator is not defined, then this utility type can't resolve the input type because it doesn't exist and will "fall back" to never.

When input is not defined, if you assign ActionInputSchema<typeof actions.contact> to a variable and try to assign a value, Typescript will complain because no value is valid. This is a way to detect something is wrong. Here what's wrong is that input is not defined.

So, I'm not sure "returns never" is clear enough for people less familiar with Typescript. Maybe we should instead say something like: "This utility type is only able to retrieve the type of an input when it is defined in your action.".

I think it's important that the text contains the keyword never.

I wouldn't explain what never is, and if you think it's important, maybe instead link to some article or TS documentation.

Suggested change

If the [`input` validator](#input-validator) is omitted, it returns `never`.

Returns `never` when [`input` validator](#input-validator) is omitted.

src/content/docs/en/reference/modules/astro-actions.mdx

sarah11918 · 2025-11-17T16:22:10Z

src/content/docs/en/reference/modules/astro-actions.mdx

+
+The following example uses `ActionInputSchema` on an action named `contact` to:
+* Retrieve the **zod schema type** for the input of the action.
+* Retrieve the expected **input type** of the action's validator.


Suggested change

* Retrieve the expected **input type** of the action's validator.

* Retrieve the expected input type of the action's validator.

I think this bolds are important because they highlight the returned data. The sentence is very specific and the important info may get lose in all the words.

src/content/docs/en/reference/modules/astro-actions.mdx

Co-authored-by: Sarah Rainsberger <[email protected]>

Co-authored-by: Armand Philippot <[email protected]>

mauriciabad · 2025-11-18T02:55:10Z

Thanks everyone for the reviews, I added some comments and suggestions. Make any edits you want, for me all outcomes are okay.

mauriciabad added 2 commits October 31, 2025 05:21

Document new ActionInputSchema utility type

0b7d353

Include Since component

be02d71

mauriciabad mentioned this pull request Oct 31, 2025

feat: Add ActionInputSchema utility type withastro/astro#14698

Open

sarah11918 added add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. merge-on-release Don't merge this before the feature is released! (MQ=approved but WAIT for feature release!) labels Nov 3, 2025

sarah11918 reviewed Nov 3, 2025

View reviewed changes

sarah11918 and others added 2 commits November 3, 2025 07:09

fix link syntax

912b668

Merge branch 'main' into patch-1

7735103

sarah11918 added the minor-release For the next minor release; in the milestone, "merge queue" when approved by Sarah! label Nov 12, 2025

sarah11918 added this to the 5.16.0 milestone Nov 12, 2025

florian-lefebvre reviewed Nov 13, 2025

View reviewed changes

src/content/docs/en/reference/modules/astro-actions.mdx Outdated Show resolved Hide resolved

src/content/docs/en/reference/modules/astro-actions.mdx Show resolved Hide resolved

mauriciabad and others added 3 commits November 17, 2025 09:01

Update version

c2d4473

Co-authored-by: Florian Lefebvre <[email protected]>

Merge branch 'main' into patch-1

b6bf0d6

Merge branch 'main' into patch-1

2b5be89

sarah11918 reviewed Nov 17, 2025

View reviewed changes

ArmandPhilippot reviewed Nov 17, 2025

View reviewed changes

src/content/docs/en/reference/modules/astro-actions.mdx Outdated Show resolved Hide resolved

mauriciabad and others added 5 commits November 18, 2025 10:45

remove bold and make sentence shorter

940169e

Co-authored-by: Sarah Rainsberger <[email protected]>

Remove bold

c84ea2d

Co-authored-by: Sarah Rainsberger <[email protected]>

Add bold

b3c57bf

Highlight correct line

3fc7e0b

Co-authored-by: Armand Philippot <[email protected]>

Merge branch 'main' into patch-1

c23454c

	A utility type that extracts the input's zod schema type from [an action handler](#defineaction). This can be useful if you need to reference an [action's validator]((#input-validator)) input type in your own type definitions.
	A utility type that extracts the input's zod schema type from [an action handler](#defineaction). This can be useful if you need to reference an [action's validator](#input-validator) input type in your own type definitions.


		A utility type that extracts the input's zod schema type from [an action handler](#defineaction). This can be useful if you need to reference an [action's validator](#input-validator) input type in your own type definitions.

		Even if the action [accepts `form`](#accept-property), `ActionInputSchema` lets you get the input type as `object` rather than [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData).


		Even if the action [accepts `form`](#accept-property), `ActionInputSchema` lets you get the input type as `object` rather than [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData).

		If the [`input` validator](#input-validator) is omitted, it returns `never`.

	If the [`input` validator](#input-validator) is omitted, it returns `never`.
	Returns `never` when [`input` validator](#input-validator) is omitted.

	* Retrieve the expected input type of the action's validator.
	* Retrieve the expected input type of the action's validator.

Uh oh!

Document new ActionInputSchema utility type #12647

Are you sure you want to change the base?

Document new ActionInputSchema utility type #12647

Conversation

mauriciabad commented Oct 31, 2025

Description

Uh oh!

netlify bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 commented Nov 12, 2025

Uh oh!

florian-lefebvre left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mauriciabad commented Nov 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Document new `ActionInputSchema` utility type #12647

Document new `ActionInputSchema` utility type #12647

netlify bot commented Oct 31, 2025 •

edited

Loading

astrobot-houston commented Oct 31, 2025 •

edited

Loading