Server Action Pattern | Bootspring Docs

Build type-safe form submissions and data mutations using Next.js Server Actions with progressive enhancement and optimistic updates.

Overview#

Server Actions are async functions that run on the server, designed for handling form submissions and data mutations. They integrate seamlessly with React's form handling and provide progressive enhancement out of the box.

When to use:

Form submissions from client components
Data mutations that need revalidation
Actions requiring progressive enhancement (works without JavaScript)
Simple CRUD operations from the UI

Key features:

Automatic form handling with action attribute
Progressive enhancement (works without JS)
Built-in revalidation with revalidatePath and revalidateTag
Type-safe with TypeScript
Works with useActionState for loading states

Code Example#

Basic Server Action#

// actions/posts.ts
'use server'

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

const CreatePostSchema = z.object({
  title: z.string().min(1, 'Title is required').max(200),
  content: z.string().optional()
})

export async function createPost(formData: FormData) {
  const { userId } = await auth()
  if (!userId) throw new Error('UNAUTHORIZED')

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

  const post = await prisma.post.create({
    data: { ...validated, authorId: userId }
  })

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

Server Action with Return Value#

// actions/posts.ts
'use server'

type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string }

export async function updatePost(
  postId: string,
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  try {
    const { userId } = await auth()
    if (!userId) {
      return { success: false, error: 'Not authenticated' }
    }

    const post = await prisma.post.findUnique({ where: { id: postId } })
    if (!post || post.authorId !== userId) {
      return { success: false, error: 'Not authorized' }
    }

    const title = formData.get('title') as string
    if (!title || title.length < 1) {
      return { success: false, error: 'Title is required' }
    }

    const updated = await prisma.post.update({
      where: { id: postId },
      data: { title }
    })

    revalidatePath(`/posts/${postId}`)
    return { success: true, data: { id: updated.id } }
  } catch (error) {
    console.error('Update post error:', error)
    return { success: false, error: 'Failed to update post' }
  }
}

Using with useActionState (React 19)#

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

import { useActionState } from 'react'
import { createPost } from '@/actions/posts'

const initialState = { error: null as string | null }

export function CreatePostForm() {
  const [state, formAction, isPending] = useActionState(
    async (prevState: typeof initialState, formData: FormData) => {
      const result = await createPost(formData)
      if (!result.success) {
        return { error: result.error }
      }
      return { error: null }
    },
    initialState
  )

  return (
    <form action={formAction}>
      {state.error && (
        <div className="text-red-500 mb-4">{state.error}</div>
      )}

      <input
        name="title"
        placeholder="Post title"
        required
        disabled={isPending}
        className="w-full p-2 border rounded"
      />

      <textarea
        name="content"
        placeholder="Content (optional)"
        disabled={isPending}
        className="w-full p-2 border rounded mt-2"
      />

      <button
        type="submit"
        disabled={isPending}
        className="mt-4 px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
      >
        {isPending ? 'Creating...' : 'Create Post'}
      </button>
    </form>
  )
}

Delete Action with Confirmation#

// actions/posts.ts
'use server'

export async function deletePost(postId: string): Promise<ActionResult<null>> {
  const { userId } = await auth()
  if (!userId) {
    return { success: false, error: 'Not authenticated' }
  }

  const post = await prisma.post.findUnique({ where: { id: postId } })
  if (!post || post.authorId !== userId) {
    return { success: false, error: 'Not authorized' }
  }

  await prisma.post.delete({ where: { id: postId } })

  revalidatePath('/posts')
  return { success: true, data: null }
}

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

import { deletePost } from '@/actions/posts'
import { useTransition } from 'react'
import { useRouter } from 'next/navigation'

export function DeleteButton({ postId }: { postId: string }) {
  const [isPending, startTransition] = useTransition()
  const router = useRouter()

  const handleDelete = () => {
    if (!confirm('Are you sure you want to delete this post?')) return

    startTransition(async () => {
      const result = await deletePost(postId)
      if (result.success) {
        router.push('/posts')
      } else {
        alert(result.error)
      }
    })
  }

  return (
    <button
      onClick={handleDelete}
      disabled={isPending}
      className="text-red-500 disabled:opacity-50"
    >
      {isPending ? 'Deleting...' : 'Delete'}
    </button>
  )
}

Optimistic Updates#

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

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

export function LikeButton({ postId, initialLiked, initialCount }: {
  postId: string
  initialLiked: boolean
  initialCount: number
}) {
  const [isPending, startTransition] = useTransition()
  const [optimistic, setOptimistic] = useOptimistic(
    { liked: initialLiked, count: initialCount },
    (state, newLiked: boolean) => ({
      liked: newLiked,
      count: newLiked ? state.count + 1 : state.count - 1
    })
  )

  const handleClick = () => {
    startTransition(async () => {
      setOptimistic(!optimistic.liked)
      await toggleLike(postId)
    })
  }

  return (
    <button onClick={handleClick} disabled={isPending}>
      {optimistic.liked ? 'Liked' : 'Like'} ({optimistic.count})
    </button>
  )
}

Usage Instructions#

Create action file: Add 'use server' directive at the top of the file
Define action function: Create async function that accepts FormData or other arguments
Validate input: Use Zod to validate form data
Handle authentication: Check user is authenticated before mutations
Revalidate data: Call revalidatePath() or revalidateTag() after mutations
Return results: Return success/error objects for client handling

Best Practices#

Use the 'use server' directive - Required at the top of server action files
Return structured results - Use { success, data, error } pattern for predictable handling
Validate all input - Never trust form data, always validate server-side
Handle errors gracefully - Catch exceptions and return user-friendly messages
Revalidate affected paths - Update cached data after mutations
Use optimistic updates - Improve perceived performance with useOptimistic
Keep actions focused - One action per mutation type

When to Use Server Actions vs Route Handlers#

Use Server Actions for:

Form submissions
Mutations from client components
Actions that need revalidation
Progressive enhancement (works without JS)

Use Route Handlers for:

Webhooks from external services
Public APIs consumed by other apps
Long-running operations
File uploads/downloads

Route Handler - For REST APIs and webhooks
Error Handling - Consistent error responses
Validation - Input validation with Zod
Forms - Form components with react-hook-form