error-handling

Error Handling and Loading States

RULE 1: Every Data-Fetching Page Needs Sibling Files

EVERY page in app/ router that does data fetching MUST have:

• loading.tsx (Suspense boundary — shown during streaming)
• error.tsx (Error boundary — must be 'use client')

loading.tsx template:

export default function Loading() {
  return (
    <div className="flex items-center justify-center min-h-[200px]">
      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
    </div>
  )
}

error.tsx template:

'use client'

export default function Error({ 
  error, 
  reset 
}: { 
  error: Error & { digest?: string }
  reset: () => void 
}) {
  return (
    <div className="flex flex-col items-center justify-center min-h-[200px] gap-4">
      <h2 className="text-xl font-semibold">Something went wrong</h2>
      <p className="text-muted-foreground">An unexpected error occurred.</p>
      <button 
        onClick={reset}
        className="px-4 py-2 bg-primary text-primary-foreground rounded-md"
      >
        Try again
      </button>
    </div>
  )
}

RULE 2: NEVER Expose Internal Errors to Clients

Server errors, database errors, and stack traces MUST stay server-side. Return generic messages to the client. Log the real error.

✅ CORRECT:

try {
  const { data, error } = await supabase.from('posts').select()
  if (error) throw error
  return data
} catch (error) {
  console.error('[POSTS_FETCH_ERROR]', error) // Detailed log server-side
  return NextResponse.json(
    { error: 'Failed to fetch posts' }, // Generic message to client
    { status: 500 }
  )
}

❌ WRONG:

} catch (error) {
  return NextResponse.json(
    { error: error.message }, // Leaks: "relation 'posts' does not exist"
    { status: 500 }
  )
}

RULE 3: Use ActionResponse for All Server Actions

Every Server Action MUST return a typed response — never throw.

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

// Usage:
export async function createPost(input: unknown): Promise<ActionResponse<Post>> {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()
  if (!user) return { success: false, error: 'Unauthorized' }

  const parsed = PostSchema.safeParse(input)
  if (!parsed.success) return { success: false, error: 'Invalid input' }

  const { data, error } = await supabase
    .from('posts')
    .insert({ ...parsed.data, user_id: user.id })
    .select()
    .single()

  if (error) {
    console.error('[CREATE_POST_ERROR]', error)
    return { success: false, error: 'Failed to create post' }
  }

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