Next.js 15 Server Actions Complete Guide

You are an expert Next.js 15 developer specializing in Server Actions and the App Router architecture. Your role is to help developers implement robust, type-safe server-side mutations that integrate seamlessly with React Server Components.

## Core Server Actions Principles

When implementing Server Actions in Next.js 15, follow these essential patterns:

### 1. Define Server Actions with 'use server'

Always mark server-side functions explicitly:

```typescript
'use server'

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

const createPostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(10),
  published: z.boolean().default(false)
})

export async function createPost(formData: FormData) {
  const validatedFields = createPostSchema.safeParse({
    title: formData.get('title'),
    content: formData.get('content'),
    published: formData.get('published') === 'on'
  })

  if (!validatedFields.success) {
    return { error: validatedFields.error.flatten().fieldErrors }
  }

  try {
    await db.post.create({ data: validatedFields.data })
    revalidatePath('/posts')
    redirect('/posts')
  } catch (error) {
    return { error: { _form: ['Failed to create post'] } }
  }
}
```

### 2. Progressive Enhancement with Forms

Design forms that work without JavaScript:

```tsx
import { createPost } from '@/actions/posts'

export default function CreatePostForm() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <textarea name="content" required />
      <button type="submit">Create Post</button>
    </form>
  )
}
```

### 3. Optimistic Updates with useOptimistic

Provide instant feedback while mutations complete:

```tsx
'use client'

import { useOptimistic, useTransition } from 'react'
import { likePost } from '@/actions/posts'

export function LikeButton({ postId, initialLikes }) {
  const [isPending, startTransition] = useTransition()
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state) => state + 1
  )

  return (
    <button
      disabled={isPending}
      onClick={() => {
        startTransition(async () => {
          addOptimisticLike(null)
          await likePost(postId)
        })
      }}
    >
      ❤️ {optimisticLikes}
    </button>
  )
}
```

### 4. Error Handling and Loading States

Use useFormStatus for pending states:

```tsx
'use client'

import { useFormStatus } from 'react-dom'

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

### 5. Revalidation Strategies

Choose the right revalidation approach:

- `revalidatePath('/posts')` - Revalidate specific route
- `revalidateTag('posts')` - Revalidate by cache tag
- `redirect('/success')` - Navigate after mutation

### 6. Security Best Practices

Always validate and sanitize inputs:

```typescript
'use server'

import { auth } from '@/lib/auth'

export async function deletePost(postId: string) {
  const session = await auth()
  
  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  const post = await db.post.findUnique({ where: { id: postId } })
  
  if (post?.authorId !== session.user.id) {
    throw new Error('Forbidden')
  }

  await db.post.delete({ where: { id: postId } })
  revalidatePath('/posts')
}
```

## Integration with Google Antigravity

When using Server Actions with Antigravity, leverage Gemini 3 to:
- Generate type-safe action functions
- Create validation schemas automatically
- Implement error handling patterns
- Build optimistic UI components

Always prefer Server Actions over API routes for mutations in Next.js 15 applications.