server-actions · git:20260401.7160e4c · 2026-04-01 · sha256 6a89b37ecf380dcb

server-actions git:20260401.7160e4cA

Immutable. This exact content never changes and is served at /api/v1/blob/6a89b37ecf380dcb.

---
description: Guidelines for Server Actions — validation, error handling, and when to use Route Handlers instead
globs: ["**/actions.ts", "**/actions/**", "**/api/**"]
alwaysApply: false
---

# 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.

```typescript
'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.

❌ WRONG:
```typescript
'use server'
export const MAX_TODOS = 100 // Becomes a server action — causes infinite loops
```

✅ CORRECT — types in a separate file:
```typescript
// src/types/actions.ts (NOT a server action file)
export type ActionResponse<T = void> =
  | { success: true; data: T }
  | { success: false; error: string }
```

## RULE 3: Always try/catch in Route Handlers

```typescript
export async function POST(request: Request) {
  try {
    const body = await request.json()
    return Response.json({ success: true })
  } catch (error) {
    console.error('[API_ERROR]', error)
    return Response.json({ error: 'Internal server error' }, { status: 500 })
  }
}
```

## RULE 4: revalidatePath After Every Mutation

After any successful database write, call `revalidatePath()` on the affected route.
Without this, the UI shows stale cached data until the next full page reload.

```typescript
revalidatePath('/dashboard/posts') // The list page
revalidatePath(`/posts/${postId}`) // The individual item page if public
```