# Actions and Forms Course: [Astro](https://www.devtutorials.ai/learn/astro) · Section: Server Development Source: https://www.devtutorials.ai/learn/astro/server/actions-and-forms > What actions are, defineAction() and the server export, groups, Zod input validation, accept form, isInputError(), calling actions from scripts and HTML forms, getActionResult(), callAction(), ActionError, redirects and securing actions. ## Actions - In **Endpoints and Server Data**, you wrote endpoints and called them with `fetch()`. - You had to read the body, check every field and build the response by hand. - An **action** is a server function you call like a normal function. Astro does the rest: - it sends the request, - checks the input with a Zod schema, - and gives you back `{ data, error }`. - In this lesson, Asha builds her like button and newsletter form with actions. **Simple lesson:** an action is a type-safe server function that your page or form can call directly. ### A Real-World Example - Asha's like button used a hand-written endpoint and `fetch()`. - Each new feature meant another endpoint, more JSON code and more checks. - With actions, she writes one function per feature in `src/actions/index.ts`. - Her browser script calls `actions.like({ slug })`, as if it were local. Press **▶ Run** and click the button. The **Terminal** shows the action running on the server.

`, }} /> What happened: - `defineAction()` described the action: its input and its handler. - The browser script imported `actions` from `astro:actions` and called `actions.like()`. - The handler ran on the server. Its return value came back as `data`. ### What You Will Learn In this lesson, you will learn: 1. How to define actions and group them. 2. How to check input with Zod, for JSON and for forms. 3. How to show input errors next to form fields. 4. How to call actions from scripts, forms and the server. 5. How to fail on purpose with `ActionError`. 6. How to redirect after success. 7. How to keep actions secure. ## Actions Basics ### Defining an Action with defineAction() - `defineAction({ input, handler })` makes one action. - `input` = a Zod schema for what the caller must send. - `handler(input, context)` = the server code. Its return value is the result. ### The server Export - **[TS]** Actions live in `src/actions/index.ts`. **[JS]** In `src/actions/index.js`. - Export them in an object called `server`. - The key is the action's name: `server.like` becomes `actions.like`. ### Organising Actions in Groups - Nest objects to group related actions: ```ts export const server = { blog: { like: defineAction({ ... }), comment: defineAction({ ... }) }, newsletter: { subscribe: defineAction({ ... }) }, }; ``` - Call them with dots: `actions.blog.like(...)`, `actions.newsletter.subscribe(...)`. Use an action when your own pages call the server. Use an endpoint when other websites or apps need a plain URL that returns JSON.
Animation: the browser calls actions.like. The input passes the Zod check, the handler runs on the server, and data or an error comes back. Browser actions.like(input) Zod check input schema handler (server) returns data {"{"} data, error {"}"} bad input stops here → error
Input is checked first. Only valid input reaches the handler.
**Simple lesson:** actions live in `src/actions/index.ts`, inside `export const server = { ... }`. ## Input Validation ### input with Zod - The `input` schema is checked **before** the handler runs. - Bad input never reaches your code. The caller gets an error instead. - Use the same Zod tools as in **Content Collections**: `z.string().min(2)`, `z.number().int()`, `z.string().email()`. ### Displaying Input Errors with isInputError() - `isInputError(error)` is `true` when the input failed the schema. - Then `error.fields` lists the messages per field: `error.fields.name` is an array of text. - Show each message next to its field. ### [TS] Type Inference from Inputs - The handler's input type comes from the schema. `name` is a `string`, `age` a `number`. - The caller's argument is checked by your editor too: `actions.like({ slugg: "x" })` is underlined. - **[JS]** The runtime checks are the same. You just do not get editor warnings. Press **▶ Run**. Try a short name and a bad email, then fix them.

`, }} /> **Simple lesson:** the Zod schema checks input first. `isInputError()` and `error.fields` let you show each problem. ## Calling Actions from Forms ### Validating Form Data with accept: "form" - HTML forms send **form data**, not JSON. - Add `accept: "form"` to the action. Astro reads the fields by their `name`, then checks them with the schema. - Numbers and checkboxes are converted for you when the schema says `z.number()` or `z.boolean()`. ### Calling Actions from an HTML Form - Set the form's `action` to the action: `
`. - The page must be **on demand** (`prerender = false`), because the server handles the post. - This works even if JavaScript is turned off in the browser. ### Reading Results with Astro.getActionResult() - After the form posts, the page renders again. - `Astro.getActionResult(actions.newsletter.subscribe)` returns `{ data, error }`, or `undefined` if the form was not sent. Press **▶ Run**. Send the form empty first, then fill it in. {result && !result.error &&

Subscribed: {result.data}

} {fieldErrors.email && {fieldErrors.email.join(", ")}}
`, }} /> A form action needs no ` `, }} /> Hiding a button is not security. Anyone can call an action with a few lines of code. Always check permissions inside the handler or in middleware. **Simple lesson:** treat every action as public. Check the user in the handler or in middleware. ## TL;DR 1. **Action** = a server function you call like a local function. `defineAction({ input, handler })`. 2. **Where** = `src/actions/index.ts`, in `export const server = { ... }`. Nest objects for groups. 3. **input** = a Zod schema, checked before the handler runs. 4. **Call from a script** = `const { data, error } = await actions.name(input)`. 5. **isInputError(error)** = schema failure. `error.fields` = messages per field. 6. **Forms** = `accept: "form"`, `
`, on-demand page. 7. **Read the form result** = `Astro.getActionResult(actions.name)`. 8. **.orThrow()** = data or a thrown error. **Astro.callAction()** = run on the server. 9. **ActionError** = fail on purpose with a code. Redirect after form success. 10. **Security** = check the user in the handler or with `getActionContext()` in middleware. ## Common mistakes
| Mistake | Wrong idea | Correct idea | What goes wrong | |---|---|---|---| | Actions not in `server` | Any export works | `export const server = { ... }` | `actions.name` is not found | | Form action without `accept: "form"` | Actions read forms by default | Add `accept: "form"` | Input error: expected JSON | | Form action on a static page | Forms work everywhere | Use `prerender = false` | The post has nowhere to go | | Using `data` without checking `error` | Calls always succeed | Check `error` first | `data` is `undefined` | | No permission check in the handler | Hidden buttons are safe | Check the session or locals | Anyone can run the action | | No redirect after a form succeeds | The page is done | `return Astro.redirect(...)` | A refresh sends the form again |
## Check Yourself ## Exercises ## What to Remember - Actions are server functions in `src/actions/index.ts`, exported in `server`. - The Zod `input` schema checks every call before the handler runs. - Call them from scripts (`{ data, error }`), from forms (`accept: "form"`) or on the server. - Throw `ActionError` to fail on purpose, and redirect after a form succeeds. - Every action is public: check the user inside it. Next: **Authentication**, where Asha builds a real login with sessions, actions and middleware.