server-action

Generate a Server Action for the following mutation: $ARGUMENTS

Rules for generation:

File placement:

• If this action is used by a single route, co-locate it in that route's directory as actions.ts
• If this action is shared across routes, place it in app/actions/ or lib/actions/
• Always add 'use server' at the top of the file (not inside the function)

Function signature:

• For form submissions: accept FormData as the parameter
• For programmatic calls from Client Components: accept a typed object parameter
• Never accept Request objects — that's a Route Handler pattern, not Server Actions

Return values:

• Return data directly on success — not { status: 200, data: ... }
• On expected errors (validation, not found), return { error: string } or throw
• Use revalidatePath() or revalidateTag() after mutations that should invalidate cached data
• Use redirect() from next/navigation if the action should navigate after completion

What NOT to generate:

• No try/catch that swallows errors silently
• No HTTP status objects
• No calling other Server Actions from within this Server Action
• No data fetching (reads) — Server Actions are for writes/mutations only

Example of what to generate:

'use server'

import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const content = formData.get('content') as string

  if (!title || !content) {
    return { error: 'Title and content are required' }
  }

  await db.post.create({ data: { title, content } })
  revalidatePath('/posts')
  redirect('/posts')
}

After generating the action, also generate:

1. The form or button component that calls it (as a Client Component if using event handlers, or with action= prop if it's a plain form)
2. Any TypeScript types needed for the parameters
3. If the form needs to display errors or pending state, use useActionState from react (NOT the deprecated useFormState from react-dom) and useFormStatus from react-dom:

'use client'
import { useActionState } from 'react'      // React 19 / Next.js 15
import { useFormStatus } from 'react-dom'

function SubmitButton() {
  const { pending } = useFormStatus()
  return <button type="submit" disabled={pending}>{pending ? 'Saving...' : 'Save'}</button>
}

export function PostForm() {
  const [state, action] = useActionState(createPost, null)
  return (
    <form action={action}>
      <input name="title" />
      {state?.error && <p>{state.error}</p>}
      <SubmitButton />
    </form>
  )
}

Ask before generating if unclear: Is this triggered by a form submission or a button click? Does it need optimistic updates?