Server Actions

Next.js Server Actions

Overview

Server Actions are asynchronous functions that execute on the server. They can be called from Client and Server Components for data mutations, form submissions, and other server-side operations.

Defining Server Actions

In Server Components

Use the 'use server' directive inside an async function:

// app/page.tsx (Server Component)
export default function Page() {
  async function createPost(formData: FormData) {
    'use server'
    const title = formData.get('title') as string
    await db.post.create({ data: { title } })
  }

  return (
    <form action={createPost}>
      <input name="title" />
      <button type="submit">Create</button>
    </form>
  )
}

In Separate Files

Mark the entire file with 'use server':

// app/actions.ts
'use server'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  await db.post.create({ data: { title } })
}

export async function deletePost(id: string) {
  await db.post.delete({ where: { id } })
}

Form Handling

Basic Form

// app/actions.ts
'use server'

export async function submitContact(formData: FormData) {
  const name = formData.get('name') as string
  const email = formData.get('email') as string
  const message = formData.get('message') as string

  await db.contact.create({
    data: { name, email, message }
  })
}

// app/contact/page.tsx
import { submitContact } from '@/app/actions'

export default function ContactPage() {
  return (
    <form action={submitContact}>
      <input name="name" required />
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button type="submit">Send</button>
    </form>
  )
}

With Validation (Zod)

// app/actions.ts
'use server'

import { z } from 'zod'

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

export async function signup(formData: FormData) {
  const parsed = schema.safeParse({
    email: formData.get('email'),
    password: formData.get('password'),
  })

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

  await createUser(parsed.data)
  return { success: true }
}

useFormState Hook

Handle form state and errors:

// app/signup/page.tsx
'use client'

import { useFormState } from 'react-dom'
import { signup } from '@/app/actions'

const initialState = {
  error: null,
  success: false,
}

export default function SignupPage() {
  const [state, formAction] = useFormState(signup, initialState)

  return (
    <form action={formAction}>
      <input name="email" type="email" />
      <input name="password" type="password" />
      {state.error && (
        <p className="text-red-500">{state.error}</p>
      )}
      <button type="submit">Sign Up</button>
    </form>
  )
}

// app/actions.ts
'use server'

export async function signup(prevState: any, formData: FormData) {
  const email = formData.get('email') as string

  if (!email.includes('@')) {
    return { error: 'Invalid email', success: false }
  }

  await createUser({ email })
  return { error: null, success: true }
}

useFormStatus Hook

Show loading states during submission:

// components/submit-button.tsx
'use client'

import { useFormStatus } from 'react-dom'

export function SubmitButton() {
  const { pending } = useFormStatus()

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Submitting...' : 'Submit'}
    </button>
  )
}

// Usage in form
import { SubmitButton } from '@/components/submit-button'

export default function Form() {
  return (
    <form action={submitAction}>
      <input name="title" />
      <SubmitButton />
    </form>
  )
}

Revalidation

revalidatePath

Revalidate a specific path:

'use server'

import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  await db.post.create({ data: { ... } })

  // Revalidate the posts list page
  revalidatePath('/posts')

  // Revalidate a dynamic route
  revalidatePath('/posts/[slug]', 'page')

  // Revalidate all paths under /posts
  revalidatePath('/posts', 'layout')
}

revalidateTag

Revalidate by cache tag:

// Fetching with tags
const posts = await fetch('https://api.example.com/posts', {
  next: { tags: ['posts'] }
})

// Server Action
'use server'

import { revalidateTag } from 'next/cache'

export async function createPost(formData: FormData) {
  await db.post.create({ data: { ... } })
  revalidateTag('posts')
}

Redirects After Actions

'use server'

import { redirect } from 'next/navigation'

export async function createPost(formData: FormData) {
  const post = await db.post.create({ data: { ... } })

  // Redirect to the new post
  redirect(`/posts/${post.slug}`)
}

Optimistic Updates

Update UI immediately while action completes:

'use client'

import { useOptimistic } from 'react'
import { addTodo } from '@/app/actions'

export function TodoList({ todos }: { todos: Todo[] }) {
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (state, newTodo: string) => [
      ...state,
      { id: 'temp', title: newTodo, completed: false }
    ]
  )

  async function handleSubmit(formData: FormData) {
    const title = formData.get('title') as string
    addOptimisticTodo(title) // Update UI immediately
    await addTodo(formData)  // Server action
  }

  return (
    <>
      <form action={handleSubmit}>
        <input name="title" />
        <button>Add</button>
      </form>
      <ul>
        {optimisticTodos.map(todo => (
          <li key={todo.id}>{todo.title}</li>
        ))}
      </ul>
    </>
  )
}

Non-Form Usage

Call Server Actions programmatically:

'use client'

import { deletePost } from '@/app/actions'

export function DeleteButton({ id }: { id: string }) {
  return (
    <button onClick={() => deletePost(id)}>
      Delete
    </button>
  )
}

Error Handling

'use server'

export async function createPost(formData: FormData) {
  try {
    await db.post.create({ data: { ... } })
    return { success: true }
  } catch (error) {
    if (error instanceof PrismaClientKnownRequestError) {
      if (error.code === 'P2002') {
        return { error: 'A post with this title already exists' }
      }
    }
    return { error: 'Failed to create post' }
  }
}

Security Considerations

1. Always validate input - Never trust client data 2. Check authentication - Verify user is authorized 3. Use CSRF protection - Built-in with Server Actions 4. Sanitize output - Prevent XSS attacks

'use server'

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

export async function deletePost(id: string) {
  const session = await auth()

  if (!session) {
    throw new Error('Unauthorized')
  }

  const post = await db.post.findUnique({ where: { id } })

  if (post.authorId !== session.user.id) {
    throw new Error('Forbidden')
  }

  await db.post.delete({ where: { id } })
}

Resources

For detailed patterns, see:

• references/form-handling.md - Advanced form patterns
• references/revalidation.md - Cache revalidation strategies
• examples/mutation-patterns.md - Complete mutation examples

Server Actions Mutation Patterns

Basic CRUD Mutations

Create

// actions/posts.ts
'use server'

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

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

export async function createPost(formData: FormData) {
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  const validated = createPostSchema.parse({
    title: formData.get('title'),
    content: formData.get('content'),
    published: formData.get('published') === 'true',
  })

  const post = await db.post.create({
    data: {
      ...validated,
      authorId: session.user.id,
    },
  })

  revalidatePath('/posts')
  redirect(`/posts/${post.id}`)
}

Update

// actions/posts.ts
'use server'

export async function updatePost(id: string, formData: FormData) {
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  // Verify ownership
  const post = await db.post.findUnique({
    where: { id },
    select: { authorId: true },
  })

  if (post?.authorId !== session.user.id) {
    throw new Error('Forbidden')
  }

  await db.post.update({
    where: { id },
    data: {
      title: formData.get('title') as string,
      content: formData.get('content') as string,
    },
  })

  revalidatePath('/posts')
  revalidatePath(`/posts/${id}`)
}

Delete

// actions/posts.ts
'use server'

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

  // Verify ownership or admin
  const post = await db.post.findUnique({
    where: { id },
    select: { authorId: true },
  })

  if (post?.authorId !== session.user.id && session.user.role !== 'admin') {
    throw new Error('Forbidden')
  }

  await db.post.delete({ where: { id } })

  revalidatePath('/posts')
  redirect('/posts')
}

Optimistic Updates

Like Button with Optimistic UI

// components/like-button.tsx
'use client'

import { useOptimistic, useTransition } from 'react'
import { toggleLike } from '@/actions/likes'

interface Props {
  postId: string
  initialLikes: number
  initialIsLiked: boolean
}

export function LikeButton({ postId, initialLikes, initialIsLiked }: Props) {
  const [isPending, startTransition] = useTransition()

  const [optimisticState, addOptimistic] = useOptimistic(
    { likes: initialLikes, isLiked: initialIsLiked },
    (state) => ({
      likes: state.isLiked ? state.likes - 1 : state.likes + 1,
      isLiked: !state.isLiked,
    })
  )

  async function handleClick() {
    startTransition(async () => {
      addOptimistic(null)
      await toggleLike(postId)
    })
  }

  return (
    <button
      onClick={handleClick}
      disabled={isPending}
      className="flex items-center gap-2"
    >
      <span className={optimisticState.isLiked ? 'text-red-500' : ''}>
        {optimisticState.isLiked ? '❤️' : '🤍'}
      </span>
      <span>{optimisticState.likes}</span>
    </button>
  )
}

// actions/likes.ts
'use server'

import { revalidateTag } from 'next/cache'
import { auth } from '@/auth'

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

  const existing = await db.like.findUnique({
    where: {
      userId_postId: {
        userId: session.user.id,
        postId,
      },
    },
  })

  if (existing) {
    await db.like.delete({
      where: { id: existing.id },
    })
  } else {
    await db.like.create({
      data: {
        userId: session.user.id,
        postId,
      },
    })
  }

  revalidateTag(`post-${postId}`)
}

Optimistic List Item

// components/todo-list.tsx
'use client'

import { useOptimistic, useRef } from 'react'
import { addTodo } from '@/actions/todos'

interface Todo {
  id: string
  text: string
  completed: boolean
}

export function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
  const formRef = useRef<HTMLFormElement>(null)

  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    initialTodos,
    (state, newTodo: Todo) => [...state, newTodo]
  )

  async function handleSubmit(formData: FormData) {
    const text = formData.get('text') as string

    // Add optimistic todo with temporary ID
    addOptimisticTodo({
      id: `temp-${Date.now()}`,
      text,
      completed: false,
    })

    formRef.current?.reset()

    // Server action will revalidate
    await addTodo(formData)
  }

  return (
    <div>
      <ul>
        {optimisticTodos.map((todo) => (
          <li
            key={todo.id}
            className={todo.id.startsWith('temp-') ? 'opacity-50' : ''}
          >
            {todo.text}
          </li>
        ))}
      </ul>

      <form ref={formRef} action={handleSubmit}>
        <input name="text" placeholder="Add todo..." required />
        <button type="submit">Add</button>
      </form>
    </div>
  )
}

Error Handling

Returning Errors to UI

// actions/newsletter.ts
'use server'

import { z } from 'zod'

export type SubscribeResult = {
  success?: boolean
  error?: string
}

const schema = z.object({
  email: z.string().email('Please enter a valid email'),
})

export async function subscribe(
  _prevState: SubscribeResult,
  formData: FormData
): Promise<SubscribeResult> {
  const result = schema.safeParse({
    email: formData.get('email'),
  })

  if (!result.success) {
    return { error: result.error.errors[0].message }
  }

  try {
    // Check if already subscribed
    const existing = await db.subscriber.findUnique({
      where: { email: result.data.email },
    })

    if (existing) {
      return { error: 'This email is already subscribed' }
    }

    await db.subscriber.create({
      data: { email: result.data.email },
    })

    return { success: true }
  } catch (error) {
    console.error('Subscribe error:', error)
    return { error: 'Something went wrong. Please try again.' }
  }
}

// components/newsletter-form.tsx
'use client'

import { useFormState } from 'react-dom'
import { subscribe } from '@/actions/newsletter'
import { SubmitButton } from './submit-button'

export function NewsletterForm() {
  const [state, formAction] = useFormState(subscribe, {})

  if (state.success) {
    return (
      <div className="bg-green-100 text-green-800 p-4 rounded">
        Thanks for subscribing!
      </div>
    )
  }

  return (
    <form action={formAction} className="space-y-4">
      <div>
        <input
          name="email"
          type="email"
          placeholder="Enter your email"
          className={state.error ? 'border-red-500' : ''}
        />
        {state.error && (
          <p className="text-red-500 text-sm mt-1">{state.error}</p>
        )}
      </div>
      <SubmitButton>Subscribe</SubmitButton>
    </form>
  )
}

Global Error Boundary

// app/error.tsx
'use client'

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    console.error('Application error:', error)
  }, [error])

  return (
    <div className="p-8 text-center">
      <h2 className="text-2xl font-bold text-red-600">Something went wrong!</h2>
      <p className="mt-2 text-gray-600">{error.message}</p>
      <button
        onClick={reset}
        className="mt-4 px-4 py-2 bg-blue-500 text-white rounded"
      >
        Try again
      </button>
    </div>
  )
}

Transaction Patterns

Multi-Step Transaction

// actions/checkout.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function processCheckout(formData: FormData) {
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  const cartItems = await db.cartItem.findMany({
    where: { userId: session.user.id },
    include: { product: true },
  })

  if (cartItems.length === 0) {
    return { error: 'Cart is empty' }
  }

  // Use transaction to ensure atomicity
  const order = await db.$transaction(async (tx) => {
    // 1. Create order
    const order = await tx.order.create({
      data: {
        userId: session.user.id,
        status: 'pending',
        total: cartItems.reduce(
          (sum, item) => sum + item.quantity * item.product.price,
          0
        ),
      },
    })

    // 2. Create order items
    await tx.orderItem.createMany({
      data: cartItems.map((item) => ({
        orderId: order.id,
        productId: item.productId,
        quantity: item.quantity,
        price: item.product.price,
      })),
    })

    // 3. Update inventory
    for (const item of cartItems) {
      await tx.product.update({
        where: { id: item.productId },
        data: {
          inventory: {
            decrement: item.quantity,
          },
        },
      })
    }

    // 4. Clear cart
    await tx.cartItem.deleteMany({
      where: { userId: session.user.id },
    })

    return order
  })

  revalidatePath('/cart')
  revalidatePath('/orders')

  return { success: true, orderId: order.id }
}

Real-time Updates with Server Actions

Polling Pattern

// components/live-data.tsx
'use client'

import { useEffect, useState, useTransition } from 'react'
import { getData } from '@/actions/data'

export function LiveData() {
  const [data, setData] = useState(null)
  const [isPending, startTransition] = useTransition()

  useEffect(() => {
    // Initial fetch
    startTransition(async () => {
      const result = await getData()
      setData(result)
    })

    // Poll every 5 seconds
    const interval = setInterval(() => {
      startTransition(async () => {
        const result = await getData()
        setData(result)
      })
    }, 5000)

    return () => clearInterval(interval)
  }, [])

  return (
    <div>
      {isPending && <span className="text-gray-400">Updating...</span>}
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  )
}

Bound Actions with Arguments

// components/post-actions.tsx
import { deletePost, publishPost } from '@/actions/posts'

export function PostActions({ postId }: { postId: string }) {
  // Bind the postId to the action
  const deleteWithId = deletePost.bind(null, postId)
  const publishWithId = publishPost.bind(null, postId)

  return (
    <div className="flex gap-2">
      <form action={publishWithId}>
        <button type="submit">Publish</button>
      </form>

      <form action={deleteWithId}>
        <button type="submit" className="text-red-600">
          Delete
        </button>
      </form>
    </div>
  )
}

// actions/posts.ts
'use server'

export async function deletePost(postId: string) {
  await db.post.delete({ where: { id: postId } })
  revalidatePath('/posts')
}

export async function publishPost(postId: string) {
  await db.post.update({
    where: { id: postId },
    data: { published: true },
  })
  revalidatePath('/posts')
  revalidatePath(`/posts/${postId}`)
}

Debounced Auto-Save

// components/auto-save-form.tsx
'use client'

import { useEffect, useRef, useState, useTransition } from 'react'
import { saveDraft } from '@/actions/drafts'

export function AutoSaveForm({ draftId, initialContent }: {
  draftId: string
  initialContent: string
}) {
  const [content, setContent] = useState(initialContent)
  const [saved, setSaved] = useState(true)
  const [isPending, startTransition] = useTransition()
  const timeoutRef = useRef<NodeJS.Timeout>()

  useEffect(() => {
    if (content === initialContent) return

    setSaved(false)

    // Debounce save
    clearTimeout(timeoutRef.current)
    timeoutRef.current = setTimeout(() => {
      startTransition(async () => {
        await saveDraft(draftId, content)
        setSaved(true)
      })
    }, 1000)

    return () => clearTimeout(timeoutRef.current)
  }, [content, draftId, initialContent])

  return (
    <div>
      <div className="flex justify-between mb-2">
        <span>Draft</span>
        <span className="text-sm text-gray-500">
          {isPending ? 'Saving...' : saved ? 'Saved' : 'Unsaved changes'}
        </span>
      </div>
      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
        className="w-full h-64 p-4 border rounded"
      />
    </div>
  )
}

// actions/drafts.ts
'use server'

export async function saveDraft(id: string, content: string) {
  await db.draft.update({
    where: { id },
    data: {
      content,
      updatedAt: new Date(),
    },
  })
}

Form Handling with Server Actions

Basic Form Setup

Server Action in Separate File

// actions/contact.ts
'use server'

export async function submitContact(formData: FormData) {
  const name = formData.get('name') as string
  const email = formData.get('email') as string
  const message = formData.get('message') as string

  await db.contact.create({
    data: { name, email, message },
  })
}

Form Component

// app/contact/page.tsx
import { submitContact } from '@/actions/contact'

export default function ContactPage() {
  return (
    <form action={submitContact}>
      <input name="name" placeholder="Name" required />
      <input name="email" type="email" placeholder="Email" required />
      <textarea name="message" placeholder="Message" required />
      <button type="submit">Send</button>
    </form>
  )
}

useFormState for Feedback

Action with Return Value

// actions/subscribe.ts
'use server'

import { z } from 'zod'

const schema = z.object({
  email: z.string().email('Invalid email address'),
})

export type SubscribeState = {
  success?: boolean
  error?: string
}

export async function subscribe(
  prevState: SubscribeState,
  formData: FormData
): Promise<SubscribeState> {
  const email = formData.get('email')

  const validated = schema.safeParse({ email })

  if (!validated.success) {
    return { error: validated.error.errors[0].message }
  }

  try {
    await db.subscriber.create({
      data: { email: validated.data.email },
    })
    return { success: true }
  } catch (error) {
    return { error: 'Failed to subscribe' }
  }
}

Form with useFormState

// components/subscribe-form.tsx
'use client'

import { useFormState } from 'react-dom'
import { subscribe, type SubscribeState } from '@/actions/subscribe'

const initialState: SubscribeState = {}

export function SubscribeForm() {
  const [state, formAction] = useFormState(subscribe, initialState)

  return (
    <form action={formAction}>
      <input
        name="email"
        type="email"
        placeholder="Enter your email"
        required
      />

      <SubmitButton />

      {state.error && (
        <p className="text-red-500">{state.error}</p>
      )}

      {state.success && (
        <p className="text-green-500">Successfully subscribed!</p>
      )}
    </form>
  )
}

useFormStatus for Loading States

// components/submit-button.tsx
'use client'

import { useFormStatus } from 'react-dom'

export function SubmitButton() {
  const { pending } = useFormStatus()

  return (
    <button
      type="submit"
      disabled={pending}
      className={pending ? 'opacity-50' : ''}
    >
      {pending ? 'Submitting...' : 'Submit'}
    </button>
  )
}

With Additional Status Info

// components/form-status.tsx
'use client'

import { useFormStatus } from 'react-dom'

export function FormStatus() {
  const { pending, data, method, action } = useFormStatus()

  if (!pending) return null

  return (
    <div className="text-gray-500">
      <p>Submitting form...</p>
      {data && <p>Fields: {Array.from(data.keys()).join(', ')}</p>}
    </div>
  )
}

Complex Form with Multiple Fields

Action

// actions/create-post.ts
'use server'

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

const createPostSchema = z.object({
  title: z.string().min(1, 'Title is required').max(200),
  content: z.string().min(10, 'Content must be at least 10 characters'),
  category: z.enum(['tech', 'lifestyle', 'business']),
  published: z.coerce.boolean().optional().default(false),
  tags: z.string().transform(str =>
    str.split(',').map(tag => tag.trim()).filter(Boolean)
  ),
})

export type CreatePostState = {
  success?: boolean
  errors?: {
    title?: string[]
    content?: string[]
    category?: string[]
    _form?: string[]
  }
}

export async function createPost(
  prevState: CreatePostState,
  formData: FormData
): Promise<CreatePostState> {
  const rawData = {
    title: formData.get('title'),
    content: formData.get('content'),
    category: formData.get('category'),
    published: formData.get('published'),
    tags: formData.get('tags'),
  }

  const validated = createPostSchema.safeParse(rawData)

  if (!validated.success) {
    return {
      errors: validated.error.flatten().fieldErrors,
    }
  }

  try {
    const post = await db.post.create({
      data: {
        ...validated.data,
        authorId: getCurrentUserId(),
      },
    })

    revalidatePath('/posts')
    redirect(`/posts/${post.id}`)
  } catch (error) {
    return {
      errors: {
        _form: ['Failed to create post. Please try again.'],
      },
    }
  }
}

Form Component

// components/create-post-form.tsx
'use client'

import { useFormState } from 'react-dom'
import { createPost, type CreatePostState } from '@/actions/create-post'

const initialState: CreatePostState = {}

export function CreatePostForm() {
  const [state, formAction] = useFormState(createPost, initialState)

  return (
    <form action={formAction} className="space-y-4">
      {/* Form-level errors */}
      {state.errors?._form && (
        <div className="bg-red-100 text-red-700 p-4 rounded">
          {state.errors._form.map((error, i) => (
            <p key={i}>{error}</p>
          ))}
        </div>
      )}

      {/* Title field */}
      <div>
        <label htmlFor="title">Title</label>
        <input
          id="title"
          name="title"
          className={state.errors?.title ? 'border-red-500' : ''}
        />
        {state.errors?.title && (
          <p className="text-red-500 text-sm">{state.errors.title[0]}</p>
        )}
      </div>

      {/* Content field */}
      <div>
        <label htmlFor="content">Content</label>
        <textarea
          id="content"
          name="content"
          rows={10}
          className={state.errors?.content ? 'border-red-500' : ''}
        />
        {state.errors?.content && (
          <p className="text-red-500 text-sm">{state.errors.content[0]}</p>
        )}
      </div>

      {/* Category select */}
      <div>
        <label htmlFor="category">Category</label>
        <select id="category" name="category">
          <option value="">Select category</option>
          <option value="tech">Technology</option>
          <option value="lifestyle">Lifestyle</option>
          <option value="business">Business</option>
        </select>
        {state.errors?.category && (
          <p className="text-red-500 text-sm">{state.errors.category[0]}</p>
        )}
      </div>

      {/* Published checkbox */}
      <div className="flex items-center gap-2">
        <input type="checkbox" id="published" name="published" value="true" />
        <label htmlFor="published">Publish immediately</label>
      </div>

      {/* Tags input */}
      <div>
        <label htmlFor="tags">Tags (comma-separated)</label>
        <input id="tags" name="tags" placeholder="react, nextjs, typescript" />
      </div>

      <SubmitButton />
    </form>
  )
}

File Upload Form

// actions/upload.ts
'use server'

import { writeFile } from 'fs/promises'
import path from 'path'

export type UploadState = {
  success?: boolean
  error?: string
  url?: string
}

export async function uploadFile(
  prevState: UploadState,
  formData: FormData
): Promise<UploadState> {
  const file = formData.get('file') as File

  if (!file || file.size === 0) {
    return { error: 'No file selected' }
  }

  // Validate file type
  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp']
  if (!allowedTypes.includes(file.type)) {
    return { error: 'Invalid file type. Only JPEG, PNG, and WebP allowed.' }
  }

  // Validate file size (5MB)
  if (file.size > 5 * 1024 * 1024) {
    return { error: 'File too large. Maximum 5MB allowed.' }
  }

  try {
    const bytes = await file.arrayBuffer()
    const buffer = Buffer.from(bytes)

    const filename = `${Date.now()}-${file.name}`
    const filepath = path.join(process.cwd(), 'public/uploads', filename)

    await writeFile(filepath, buffer)

    return {
      success: true,
      url: `/uploads/${filename}`,
    }
  } catch (error) {
    return { error: 'Failed to upload file' }
  }
}

Upload Form Component

// components/upload-form.tsx
'use client'

import { useFormState } from 'react-dom'
import { useState } from 'react'
import { uploadFile, type UploadState } from '@/actions/upload'

const initialState: UploadState = {}

export function UploadForm() {
  const [state, formAction] = useFormState(uploadFile, initialState)
  const [preview, setPreview] = useState<string | null>(null)

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0]
    if (file) {
      setPreview(URL.createObjectURL(file))
    }
  }

  return (
    <form action={formAction} className="space-y-4">
      <div>
        <label htmlFor="file" className="block">
          Choose an image
        </label>
        <input
          type="file"
          id="file"
          name="file"
          accept="image/jpeg,image/png,image/webp"
          onChange={handleFileChange}
        />
      </div>

      {preview && (
        <div>
          <img src={preview} alt="Preview" className="max-w-xs rounded" />
        </div>
      )}

      <SubmitButton />

      {state.error && (
        <p className="text-red-500">{state.error}</p>
      )}

      {state.success && state.url && (
        <div className="text-green-500">
          <p>Upload successful!</p>
          <img src={state.url} alt="Uploaded" className="max-w-xs mt-2" />
        </div>
      )}
    </form>
  )
}

Form with Dynamic Fields

// components/dynamic-form.tsx
'use client'

import { useFormState } from 'react-dom'
import { useState } from 'react'
import { submitItems } from '@/actions/items'

export function DynamicForm() {
  const [state, formAction] = useFormState(submitItems, {})
  const [items, setItems] = useState([{ id: 1, value: '' }])

  const addItem = () => {
    setItems(prev => [...prev, { id: Date.now(), value: '' }])
  }

  const removeItem = (id: number) => {
    setItems(prev => prev.filter(item => item.id !== id))
  }

  return (
    <form action={formAction}>
      {items.map((item, index) => (
        <div key={item.id} className="flex gap-2">
          <input
            name={`items[${index}]`}
            placeholder={`Item ${index + 1}`}
          />
          <button
            type="button"
            onClick={() => removeItem(item.id)}
          >
            Remove
          </button>
        </div>
      ))}

      <button type="button" onClick={addItem}>
        Add Item
      </button>

      <SubmitButton />
    </form>
  )
}

Process Dynamic Fields

// actions/items.ts
'use server'

export async function submitItems(
  prevState: unknown,
  formData: FormData
) {
  // Get all items from form
  const items: string[] = []
  let index = 0

  while (formData.has(`items[${index}]`)) {
    const value = formData.get(`items[${index}]`) as string
    if (value.trim()) {
      items.push(value.trim())
    }
    index++
  }

  // Process items...
  await db.item.createMany({
    data: items.map(name => ({ name })),
  })

  return { success: true, count: items.length }
}

Progressive Enhancement

Forms work without JavaScript enabled:

// components/search-form.tsx
import { searchPosts } from '@/actions/search'

export function SearchForm() {
  return (
    <form action={searchPosts}>
      <input name="q" placeholder="Search..." />
      <button type="submit">Search</button>
    </form>
  )
}

// actions/search.ts
'use server'

import { redirect } from 'next/navigation'

export async function searchPosts(formData: FormData) {
  const query = formData.get('q') as string
  redirect(`/search?q=${encodeURIComponent(query)}`)
}

Revalidation with Server Actions

Overview

After mutations, revalidate cached data to reflect changes:

• revalidatePath() - Invalidate specific routes
• revalidateTag() - Invalidate by cache tag

revalidatePath

Basic Usage

// actions/posts.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  const post = await db.post.create({
    data: {
      title: formData.get('title') as string,
      content: formData.get('content') as string,
    },
  })

  // Revalidate the posts list page
  revalidatePath('/posts')
}

Path Types

// Revalidate a specific page
revalidatePath('/posts')

// Revalidate a dynamic route
revalidatePath('/posts/[slug]', 'page')

// Revalidate a layout (and all pages using it)
revalidatePath('/posts', 'layout')

// Revalidate everything
revalidatePath('/', 'layout')

Revalidate Multiple Paths

// actions/update-post.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function updatePost(id: string, formData: FormData) {
  const post = await db.post.update({
    where: { id },
    data: {
      title: formData.get('title') as string,
      content: formData.get('content') as string,
    },
  })

  // Revalidate both the list and detail pages
  revalidatePath('/posts')
  revalidatePath(`/posts/${post.slug}`)
}

With Dynamic Segments

// actions/category.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function updateCategory(categorySlug: string, formData: FormData) {
  await db.category.update({
    where: { slug: categorySlug },
    data: { name: formData.get('name') as string },
  })

  // Revalidate the specific category page
  revalidatePath(`/categories/${categorySlug}`)

  // Also revalidate all product pages in this category
  revalidatePath('/products/[...slug]', 'page')
}

revalidateTag

Setup Tags in Data Fetching

// lib/data.ts
export async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { tags: ['posts'] },
  })
  return res.json()
}

export async function getPost(id: string) {
  const res = await fetch(`https://api.example.com/posts/${id}`, {
    next: { tags: ['posts', `post-${id}`] },
  })
  return res.json()
}

export async function getUser(id: string) {
  const res = await fetch(`https://api.example.com/users/${id}`, {
    next: { tags: ['users', `user-${id}`] },
  })
  return res.json()
}

Revalidate by Tag

// actions/posts.ts
'use server'

import { revalidateTag } from 'next/cache'

export async function createPost(formData: FormData) {
  await db.post.create({
    data: {
      title: formData.get('title') as string,
    },
  })

  // Invalidate all data tagged with 'posts'
  revalidateTag('posts')
}

export async function updatePost(id: string, formData: FormData) {
  await db.post.update({
    where: { id },
    data: { title: formData.get('title') as string },
  })

  // Invalidate just this specific post
  revalidateTag(`post-${id}`)
}

export async function deletePost(id: string) {
  await db.post.delete({ where: { id } })

  // Invalidate both the specific post and the list
  revalidateTag(`post-${id}`)
  revalidateTag('posts')
}

Multiple Tags

// actions/user.ts
'use server'

import { revalidateTag } from 'next/cache'

export async function updateUserProfile(userId: string, formData: FormData) {
  await db.user.update({
    where: { id: userId },
    data: {
      name: formData.get('name') as string,
      bio: formData.get('bio') as string,
    },
  })

  // Revalidate user data
  revalidateTag(`user-${userId}`)

  // Also revalidate their posts (which show author info)
  revalidateTag(`posts-by-${userId}`)
}

Combining revalidatePath and revalidateTag

// actions/blog.ts
'use server'

import { revalidatePath, revalidateTag } from 'next/cache'

export async function publishPost(id: string) {
  const post = await db.post.update({
    where: { id },
    data: { published: true },
  })

  // Revalidate cached API data by tag
  revalidateTag('posts')
  revalidateTag(`post-${id}`)

  // Revalidate rendered pages by path
  revalidatePath('/posts')
  revalidatePath(`/posts/${post.slug}`)
  revalidatePath('/') // Home page might show latest posts
}

Revalidation Patterns

Optimistic Update + Revalidation

// components/like-button.tsx
'use client'

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

interface Props {
  postId: string
  initialLikes: number
  isLiked: boolean
}

export function LikeButton({ postId, initialLikes, isLiked }: Props) {
  const [isPending, startTransition] = useTransition()
  const [optimisticState, addOptimistic] = useOptimistic(
    { likes: initialLikes, isLiked },
    (state, _action) => ({
      likes: state.isLiked ? state.likes - 1 : state.likes + 1,
      isLiked: !state.isLiked,
    })
  )

  const handleLike = () => {
    startTransition(async () => {
      addOptimistic(null)
      await likePost(postId) // This will revalidate
    })
  }

  return (
    <button onClick={handleLike} disabled={isPending}>
      {optimisticState.isLiked ? '❤️' : '🤍'} {optimisticState.likes}
    </button>
  )
}

// actions/posts.ts
'use server'

import { revalidateTag } from 'next/cache'

export async function likePost(postId: string) {
  const userId = await getCurrentUserId()

  await db.like.upsert({
    where: {
      userId_postId: { userId, postId },
    },
    create: { userId, postId },
    update: {},
  })

  revalidateTag(`post-${postId}`)
}

Cascade Revalidation

// actions/comments.ts
'use server'

import { revalidateTag, revalidatePath } from 'next/cache'

export async function addComment(postId: string, formData: FormData) {
  const comment = await db.comment.create({
    data: {
      postId,
      content: formData.get('content') as string,
      authorId: await getCurrentUserId(),
    },
    include: { post: true },
  })

  // Revalidate the specific post (comment count changed)
  revalidateTag(`post-${postId}`)

  // Revalidate comments for this post
  revalidateTag(`comments-${postId}`)

  // Revalidate the post page
  revalidatePath(`/posts/${comment.post.slug}`)

  // Revalidate "recent comments" widgets
  revalidateTag('recent-comments')
}

Conditional Revalidation

// actions/posts.ts
'use server'

import { revalidatePath, revalidateTag } from 'next/cache'

export async function updatePost(id: string, formData: FormData) {
  const wasPublished = await db.post.findUnique({
    where: { id },
    select: { published: true },
  })

  const post = await db.post.update({
    where: { id },
    data: {
      title: formData.get('title') as string,
      published: formData.get('published') === 'true',
    },
  })

  // Always revalidate the specific post
  revalidateTag(`post-${id}`)
  revalidatePath(`/posts/${post.slug}`)

  // Only revalidate the list if publish status changed
  if (wasPublished?.published !== post.published) {
    revalidateTag('posts')
    revalidatePath('/posts')
    revalidatePath('/') // Feed page
  }
}

Route Handler Revalidation

// app/api/revalidate/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { revalidateTag, revalidatePath } from 'next/cache'

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidate-secret')

  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ error: 'Invalid secret' }, { status: 401 })
  }

  const body = await request.json()

  if (body.tag) {
    revalidateTag(body.tag)
  }

  if (body.path) {
    revalidatePath(body.path)
  }

  return NextResponse.json({ revalidated: true, now: Date.now() })
}

On-Demand Revalidation from External Webhook

// app/api/webhook/cms/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { revalidateTag } from 'next/cache'

export async function POST(request: NextRequest) {
  const signature = request.headers.get('x-webhook-signature')
  const body = await request.json()

  // Verify webhook signature
  if (!verifyWebhookSignature(signature, body)) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 })
  }

  const { event, data } = body

  switch (event) {
    case 'post.created':
    case 'post.updated':
    case 'post.deleted':
      revalidateTag('posts')
      revalidateTag(`post-${data.id}`)
      break

    case 'user.updated':
      revalidateTag(`user-${data.id}`)
      break

    case 'cache.purge':
      // Full cache purge
      revalidateTag('all')
      break
  }

  return NextResponse.json({ success: true })
}

Debugging Revalidation

// actions/debug.ts
'use server'

import { revalidatePath, revalidateTag } from 'next/cache'

export async function debugRevalidate(target: string, type: 'path' | 'tag') {
  console.log(`Revalidating ${type}: ${target}`)

  if (type === 'tag') {
    revalidateTag(target)
  } else {
    revalidatePath(target)
  }

  console.log(`Revalidation complete at: ${new Date().toISOString()}`)
}