toolhive-cloud-ui copilot-instructions.md

GitHub Copilot Instructions - ToolHive Cloud UI

Project Context

This is a Next.js 16 App Router application for visualizing MCP (Model Context Protocol) servers running in user infrastructure. It's an open-source project using TypeScript, React 19, Tailwind CSS 4, and Better Auth for OIDC authentication.

Core Architecture Principles

• Server Components by default - Use Client Components ('use client') only when needed (event handlers, browser APIs, state hooks)
• 🚫 NEVER USE any TYPE - STRICTLY FORBIDDEN. Use unknown with type guards or proper types
• Stateless authentication - JWT-based sessions, no server-side storage
• hey-api generated client - Never create manual fetch logic, always use generated hooks
• async/await over promises - No .then() chains, use async/await for readability

⚠️ Next.js App Router - Validate Before Suggesting

This is Next.js 16 with App Router - Before suggesting code, verify against Next.js Documentation:

Common mistakes to flag:

• ❌ Pages Router patterns (getServerSideProps, getStaticProps, _app.js, _document.js)
• ❌ Custom routing logic (use file-system routing: page.tsx, layout.tsx)
• ❌ Missing 'use client' when using hooks, events, or browser APIs
• ❌ Adding 'use client' to Server Components unnecessarily
• ❌ Not understanding what Server Components can/cannot do
• ❌ Ignoring Next.js caching (next: { revalidate, tags })

Key App Router concepts:

• File conventions: page.tsx (route), layout.tsx (shared UI), loading.tsx (loading state), error.tsx (error boundary)
• Server Components (default): No hooks, no events, can fetch data directly with async/await
• Client Components ('use client'): Use when you need hooks, events, browser APIs
• Server Actions ('use server'): For mutations, better than API routes for simple cases
• Caching: Use revalidatePath(), revalidateTag() for on-demand cache updates