server-actions

Server Actions vs Route Handlers

When to Use Server Actions

• Form submissions (POST with user data)
• Mutations triggered from UI (create, update, delete)
• Operations needing cookie/session access
• Revalidation of cached pages after a mutation

When to Use Route Handlers (app/api/**)

• Webhooks (Stripe, GitHub — external services calling your API)
• Public API endpoints (no auth needed or API key auth)
• File upload/download streams
• Third-party OAuth callbacks
• CORS-required endpoints

RULE 1: Always Use Typed ActionResponse

Every Server Action MUST return ActionResponse<T> — never throw, never leak internals.

'use server'
import { z } from 'zod'
import { createClient } from '@/lib/supabase/server'
import { revalidatePath } from 'next/cache'

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

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

export async function createTodo(
  formData: FormData
): Promise<ActionResponse<{ id: string }>> {
  // 1. Auth first
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()
  if (!user) return { success: false, error: 'Unauthorized' }

  // 2. Validate
  const parsed = CreateTodoSchema.safeParse({ title: formData.get('title') })
  if (!parsed.success) {
    return { success: false, error: parsed.error.issues[0].message }
  }

  // 3. Execute
  const { data, error } = await supabase
    .from('todos')
    .insert({ title: parsed.data.title, user_id: user.id })
    .select('id')
    .single()

  if (error) {
    console.error('[CREATE_TODO_ERROR]', error) // Server-side only
    return { success: false, error: 'Failed to create todo' } // Generic to client
  }

  revalidatePath('/todos')
  return { success: true, data: { id: data.id } }
}

RULE 2: Never Export Non-Action Values from 'use server' Files

Files with 'use server' export ONLY async functions. Never export constants, types, or synchronous functions from these files.