qcast-front/.agents/skills/next-best-practices/suspense-boundaries.md

Suspense Boundaries

Client hooks that cause CSR bailout without Suspense boundaries.

useSearchParams

Always requires Suspense boundary in static routes. Without it, the entire page becomes client-side rendered.

// Bad: Entire page becomes CSR
'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()
  return <div>Query: {searchParams.get('q')}</div>
}

// Good: Wrap in Suspense
import { Suspense } from 'react'
import SearchBar from './search-bar'

export default function Page() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SearchBar />
    </Suspense>
  )
}

usePathname

Requires Suspense boundary when route has dynamic parameters.

// In dynamic route [slug]
// Bad: No Suspense
'use client'
import { usePathname } from 'next/navigation'

export function Breadcrumb() {
  const pathname = usePathname()
  return <nav>{pathname}</nav>
}

// Good: Wrap in Suspense
<Suspense fallback={<BreadcrumbSkeleton />}>
  <Breadcrumb />
</Suspense>

If you use generateStaticParams, Suspense is optional.

Quick Reference

Hook	Suspense Required
useSearchParams()	Yes
usePathname()	Yes (dynamic routes)
useParams()	No
useRouter()	No