withastro / docs

Astro documentation
https://docs.astro.build/
MIT License
1.34k stars 1.5k forks source link

Missing docs for `Astro.callAction` in `guides/actions` #9458

Closed Rados51 closed 2 days ago

Rados51 commented 1 month ago

📚 Subject area/topic

Actions

📋 Suggested page

https://docs.astro.build/en/guides/actions/

📋 General description or bullet points (if proposing new content)

There are completely missing docs (on this page) for correct calls from server-side Astro component. If we call it from Astro component with actions.getGreeting instead of Astro.callAction(...), the context is non-existing. I was just scratching my head for a few minutes until I found out the correct way.

// ❌ Wrong
await actions.getGreeting({ name: "Bob" });
// ✅ Correct
await Astro.callAction(actions.getGreeting, { name: "Bob" });

🖥️ Reproduction of code samples in StackBlitz

No response

sarah11918 commented 1 month ago

Thanks for pointing this out! I know the release notes from where this utility function was introduced are here: https://github.com/withastro/astro/releases/tag/astro%404.13.1

I can see that the API reference docs were added at that time, but an example of calling a function server-side wasn't included in the final stable documentation. I'll ask @bholmesdev to let us know whether there is a reason for not showing this on the main page (discouraging this use?). If so, maybe we can make sure there's at least a convenient link to the two functions since they're not in the Actions section itself, and might be hard to find!

bholmesdev commented 1 month ago

Thanks for flagging @sarah11918! Yes, we considered calling actions server-side as a more niche use case, so we left to an API reference and a clear error message instead of a Guide entry. Always a tough balance to strike with separate guides and references. I can't see a heading where a link would make sense, so maybe we should just bite the bullet and add a brief section at the end of the guide docs. Would you be interested in contributing @Rados51?

Rados51 commented 1 month ago

@bholmesdev Sure! I am just overwhelmed with work for the next few days, but after that, I will try my best!

sarah11918 commented 1 month ago

Thank you @Rados51 ! You can feel free to use this space for any questions or rough drafts, or you can submit a PR directly if you feel confident you know what would have helped you if it were in the guide! 🙌