feat(astro:actions): add docs for missing public APIs #12596

ArmandPhilippot · 2025-10-20T15:28:24Z

Description (required)

Adds some missing documented imports to the list: getActionContext and getActionPath.
Adds docs for ACTION_QUERY_PARAMS and actions.
Adds an astro:actions types section with docs for ActionAPIContext, ActionClient, ActionErrorCode, ActionReturnType, and SafeResult.
Adds a few more usage examples.
Updates most of the types either to fix them or to add links to the new headings
- I also simplified some types. For example, I replaced ActionClient<any, any, any> with ActionClient because this is always <any, any, any> and it seems to be an implementation detail rather than something useful to the end-user. And because we now have docs for the types, I think it makes it easier to understand.
- Fixes the defineAction() type: accept was missing while we were documenting it under input. Not sure if there was a reason for that, maybe we should use the same heading level as the others to avoid any confusion?
- To avoid long/unreadable types and because we have a precedent, I used one Types: with a list instead of using an union.
Moves the codes list from code (in ActionError) to the new ActionErrorCode heading. And, actually, replace the outdated list with a description of the expected format and an external link.
Rewords some existing descriptions for consistency and to follow our API references guide... there are already a lot of changes so, while I'm here, I think a few more updates doesn't change much the work of translators (maybe reviewers tough, sorry!).
Removes Since when the version is the same as the module
Adds a few new links in the Actions guide (and fix full > subset).

Things we might want to consider

The ACTION_ERROR_CODES list was expanded in Expand ActionError codes to include all IANA HTTP error codes astro#13769 (with some renaming). This list is quite long and I don't think this should be the role of Astro to describe them. Especially since some of them are defined as reserved for future use (e.g. PAYMENT_REQUIRED). If we think otherwise, happy to add back a full list instead.
Should we precise where methods can be imported/used? For example, defineAction() and getActionContext() will throw on the client: https://github.com/withastro/astro/blob/main/packages/astro/src/actions/runtime/client.ts I think the current description could be enough, but maybe we want to be more explicit.

Not documented

Based on Florian's feedback, some of the available imports are not documented. I think it's fine (NWTWWHB) and they should be removed in v6.

See the list of undocumented imports


import {
  type Actions,
  type ActionAccept,
  type ActionHandler,
  type AstroActionContext,
  type SerializedActionResult,
  ACTION_ERROR_CODES,
  ActionInputError,
  appendForwardSlash,
  astroCalledServerError,
  callSafely,
  deserializeActionResult,
  formDataToObject,
  getActionQueryString,
  serializeActionResult,
} from "astro:actions";

Implementation links

There are a lot of changes, so I tried to keep track of the links to help you review the accuracy of the API blocks (type/since).
I haven't updated those list, so they include undocumented imports too.

Details of the "regular" imports:

appendForwardSlash(): since 5.0.6, see fix(actions): support trailing slash astro#12657
astroCalledServerError(): no since, it's been there since the Actions stable release
callSafely(): no since, it's been there since the Actions stable release
defineAction():
- no since, it's been there since the Actions stable release
- default: the "real" default for accept is undefined, but only form changes the behavior so I think it's safe to say json is the default here.
deserializeActionResult(): no since, it's been there since the Actions stable release
formDataToObject(): no since, it's been there since the Actions stable release
getActionContext(): since 5.0.0, see Actions middleware astro#12373
getActionPath(): since 5.1.0
getActionQueryString(): no since, it's been there since the Actions stable release
isActionError(): no since, it's been there since the Actions stable release
isInputError(): no since, it's been there since the Actions stable release
serializeActionResult(): no since, it's been there since the Actions stable release
ACTION_ERROR_CODES: no since, it's been there since the Actions stable release
ACTION_QUERY_PARAMS: no since, it's been there since the Actions stable release
ActionError: no since, it's been there since the Actions stable release
ActionInputError: no since, it's been there since the Actions stable release

Details of the type imports:

Actions: no since, it's been there since the Actions stable release
ActionAPIContext: no since, it's been there since the Actions stable release
ActionAccept: no since, it's been there since the Actions stable release
ActionClient: no since, it's been there since the Actions stable release
ActionErrorCode: no since, it's been there since the Actions stable release
ActionHandler: no since, it's been there since the Actions stable release
ActionReturnType: no since, it's been there since the Actions stable release
AstroActionContext: since 5.0.0 under a different name. Since 5.4.2 with the current name, see refactor(core): move actions inside core astro#13262
SafeResult: no since, it's been there since the Actions stable release
SerializedActionResult: no since, it's been there since the Actions stable release

Related issues & labels (optional)

Closes Missing Actions API in the reference #12570
Suggested label: add new content, improve or update documentation

Closes withastro#12570

netlify · 2025-10-20T15:29:58Z

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`c4165c4`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68ff91e725cbf90008fd4f6c
😎 Deploy Preview	https://deploy-preview-12596--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-20T15:33:49Z

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

ArmandPhilippot · 2025-10-22T21:54:54Z

I think I've done all the changes I noticed here... Sorry for the Github diff: some content was already there but was moved.

I'm pinging @florian-lefebvre (no rush!) because I need a technical review to check the accuracy and if some things should be removed in v6, but anyone else is welcome to review this one!

I tried to keep a track of all the changes in the first post but there are a lot of changes so I'm not sure how readable/understandable it is. As explained in the issue, I noticed a lack of documentation for all the following imports:

import {
  ACTION_ERROR_CODES,
  ACTION_QUERY_PARAMS,
  ActionInputError,
  appendForwardSlash,
  astroCalledServerError,
  callSafely,
  deserializeActionResult,
  formDataToObject,
  getActionQueryString,
  serializeActionResult,
  type Actions,
  type ActionAPIContext,
  type ActionAccept,
  type ActionClient,
  type ActionErrorCode,
  type ActionHandler,
  type ActionReturnType,
  type AstroActionContext,
  type SafeResult,
  type SerializedActionResult,
} from "astro:actions";

So I would need a technical point of view for all of them, with some exceptions listed below:

Among them, I think some shouldn't be documented:
- type Actions: I think it is only meant to type the actions export and shouldn't be used directly by the user?
- astroCalledServerError: I don't see a use case for it... this sounds like an internal function to me.
- callSafely: I don't see a use case for it... this sounds like an internal function to me.
- ACTION_ERROR_CODES: I think the constant itself is not useful for users, only the ActionErrorCode type built from the constant?
- ACTION_QUERY_PARAMS: same I think this is internal and this is only useful through utilities like getActionQueryString()
deserializeActionResult and serializeActionResult were already documented but as methods returned by getActionContext, not as imports from astro:actions. So I mostly moved around the docs here and duplicated the headings. I couldn't find a use case to prefer one over the other... so maybe this is something that should be updated? I mean either get them from getActionContext or as top level imports?

I added docs for:

appendForwardSlash but if we move things in v6, I think this could be a good candidate? This doesn't seem related to actions specifically and so it sounds a bit weird to document it here.
ActionInputError but I don't think there is a real use case for end-users because of isInputError

And because your issue was specifically about orThrow and queryString they are under ActionClient. Feel free to suggest a more accurate description!

I'm not quite sure about the organization. I documented some properties under their types but maybe it could be more useful under the related function... But, we can think about this later!

(If you need direct links to the implementation, they are listed under a details in Implementation links in the first post)

EDIT: I was also not sure about an use case for ActionReturnType, so I'm not confident about the description...

florian-lefebvre · 2025-10-23T09:11:05Z

Thanks a lot! Before reviewing the content, let's agree on what not to document so we can remove them more easily in v6. For me:

ACTION_ERROR_CODES: do not document (internal)
ACTION_QUERY_PARAMS: document. This is actually useful for advanced cases (I've used it)
ActionInputError: do not document (internal)
appendForwardSlash: do not document (internal)
astroCalledServerError: do not document (internal)
callSafely: do not document (internal)
deserializeActionResult: do not document (probably better to have one source of truth with getActionContext()?)
formDataToObject: do not document (internal)
getActionQueryString: do not document (internal)
serializeActionResult: do not document (probably better to have one source of truth with getActionContext()?)
type Actions: do not document (we'll need to update the typegen in v6)
type ActionAPIContext: document
type ActionAccept: do not document (unless it's useful for something?)
type ActionClient: document (advanced but useful for generics)
type ActionErrorCode: document (and link to somewhere)
type ActionHandler: maybe not document? I feel like that can be explained as part of ActionClient
type ActionReturnType: document
type AstroActionContext: do not document (getActionContext() is the same)
type SafeResult: do not document (most people don't need it)
type SerializedActionResult: do not document (most people don't need it)

That's what I'm thinking but I may be wrong, happy to discuss further! Am I missing something?

ArmandPhilippot · 2025-10-23T09:54:53Z

Thanks! Except maybe SafeResult (see below my reasoning), everything makes sense to me.

ACTION_QUERY_PARAMS: document. This is actually useful for advanced cases (I've used it)

Oh okay, I'll need your help to describe when this is useful then! 😅

type ActionAccept: do not document (unless it's useful for something?)

Probably not. It seems the accept property in defineAction is rather a static value.

type ActionHandler: maybe not document? I feel like that can be explained as part of ActionClient

I'm not sure I see the relationship with ActionClient. But I agree the type might not be useful, we can describe it directly in the handler() property of defineAction!

type AstroActionContext: do not document (getActionContext() is the same)

Makes sense! This is what I meant with "I documented some properties under their types but maybe it could be more useful under the related function...", so I agree this is probably not useful.

type SafeResult: do not document (most people don't need it)

While users might not need to use it directly, maybe this is still useful to describe the format? ie:

Type: { data: TOutput, error: undefined } | { data: undefined, error: ActionError }

Because many functions uses this and so we can link to a single place?

florian-lefebvre · 2025-10-23T10:04:00Z

I'm not sure I see the relationship with ActionClient. But I agree the type might not be useful, we can describe it directly in the handler() property of defineAction!

Sorry yes that's what I meant!

Because many functions uses this and so we can link to a single place?

SGTM

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

sarah11918 · 2025-10-24T12:34:47Z

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

 </p>

-`serializeActionResult()` will serialize an action result to JSON for persistence. This is required to properly handle non-JSON return values like `Map` or `Date` as well as the `ActionError` object.
+Serializes an action result to JSON for persistence. This is required to properly handle non-JSON return values like `Map` or `Date` as well as the `ActionError` object.


Such nice editing choices! 🙌

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

sarah11918

Just left some comments below based on the text (and not yet looking at deploy preview to make sure all these code blocks render properly etc.).

There is some amazing writing here, and this is shaping up to be super high quality and helpful! Thank you both for the effort on these pages! 🙌

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

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

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

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

florian-lefebvre

LGTM thank you!

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

sarah11918

Putting this stuff in the guide feels WAY better, I think! Thank you Armand!

src/content/docs/en/guides/actions.mdx

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

ArmandPhilippot · 2025-10-27T13:38:32Z

Thanks @sarah11918 , I pushed a new commit with your two suggestions! I was a bit annoyed to have to repeat more or less the same information before, so I agree this makes more sense. 😄 I let you check the wording, but, yes, this looks better now!

yanthomasdev

LGTM! Amazing work here 🙌

sarah11918

Love it! Thank you everyone! Let's Get That Money! 💰

ArmandPhilippot · 2025-10-27T15:54:35Z

Thanks again everyone ❤️ , let's merge this! 🫡

See withastro#12596

trueberryless · 2025-11-06T13:50:39Z

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

+  getUserOrThrow: defineAction({
+    accept: 'form',
+    handler: async (_, { locals }) => {
+      if (locals.user?.name !== 'florian') {


Sorry that I am little very late to the party and that I criticize here, but is this a good example for "Not authorized". Personally, I find it a little bit confusing that the user is unauthorized, when they are not "florian". I mean, I love such easter eggs in the docs, but I'm not sure if they are maybe too confusing here...

Lol I completely missed that! I don't have strong opinions on this, I'll let others answer

I'm not an actions expert so I look at examples in the source code. 😅 I don't recall the exact example but I recall I adapt it a bit because the value seemed weird or something like that.

I guess we could update it with something like locals.user?.role !== 'admin' if you think this is better?

Sorry for the delayed answer, but personally I would find the admin check more fitting. However, as I think I might be the only one that was confused by it, we might as well just leave it and if more people complain, we can update it... Would that be fine for you?

Both work for me. But if you find this confusing, feel free to submit a PR to update the example! You may not be the only one, others might be hesitant to report this... So, as long as it's correct, an update can be helpful for others!

feat(astro:actions): add docs for missing public APIs

1304d49

Closes withastro#12570

ArmandPhilippot added improve or update documentation Enhance / update existing documentation (e.g. add example, improve description, update for changes) add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. labels Oct 20, 2025

ArmandPhilippot added 18 commits October 21, 2025 15:30

replace the error codes list with a link to IANA

2c246b4

add docs for ActionInputError and an example for ActionError

aa3c616

add description for actions and remove type Actions

415ded6

add appendForwardSlash description

6e13d8c

remove astroCalledServerError

1999276

remove callSafely

5b5cd75

add docs for formDataToObject

29d1987

add getActionQueryString and remove ACTION_QUERY_PARAMS

774e7bf

add docs for remaining imports

66680e9

remove ACTION_ERROR_CODES

cbc48cc

fix broken link

34e86ca

simplify types

0007e28

small reorganization

1ec2474

add usage example for isActionError

9f64a4d

reword some existing description to use definition style

a64fe8c

internal linking

f9d758f

more rewording

b9506b7

add linking from the Actions guide

2995b9e

ArmandPhilippot marked this pull request as ready for review October 22, 2025 21:57

Merge branch 'main' into feat/add-actions-api-references

c21e4d8

florian-lefebvre mentioned this pull request Oct 23, 2025

Cleanup actions public API withastro/astro#14608

Open

sarah11918 reviewed Oct 24, 2025

View reviewed changes