\n
\n )\n}\n\nCritical gotcha: redirect(), notFound(), forbidden(), and unauthorized() throw special errors. Never catch them in try/catch:\n\n// BAD: redirect throw is caught — navigation fails!\ntry {\n await db.post.create({ data })\n redirect(`/posts/${post.id}`)\n} catch (error) {\n return { error: 'Failed' } // Catches the redirect too!\n}\n\n// GOOD: Call redirect outside try-catch\nlet post\ntry { post = await db.post.create({ data }) }\ncatch (error) { return { error: 'Failed' } }\nredirect(`/posts/${post.id}`)"
},
{
"title": "Streaming with Suspense",
"body": "export default async function ProductPage({ params }: Props) {\n const { id } = await params\n const product = await getProduct(id) // Blocking — loads first\n\n return (\n Something went wrong!
\n \n\n
\n )\n}"
},
{
"title": "Hooks That Require Suspense Boundaries",
"body": "HookSuspense RequireduseSearchParams()Always (or entire page becomes CSR)usePathname()In dynamic routesuseParams()NouseRouter()No"
},
{
"title": "Performance",
"body": "Always use next/image over ...
Fix invalid HTML nestingThird-party scripts modifying DOMUse next/script with afterInteractive"
},
{
"title": "Self-Hosting",
"body": "See self-hosting.md for Docker, PM2, cache handlers, and deployment checklist.\n\nKey points:\n\nUse output: 'standalone' for Docker — creates minimal production bundle\nCopy public/ and .next/static/ separately (not included in standalone)\nSet HOSTNAME=\"0.0.0.0\" for containers\nMulti-instance ISR requires a custom cache handler (Redis/S3) — filesystem cache breaks\nSet health check endpoint at /api/health"
},
{
"title": "NEVER Do",
"body": "NeverWhyInsteadAdd 'use client' by defaultBloats client bundle, loses Server Component benefitsServer Components are default — add 'use client' only for interactivityMake client components asyncNot supported — will crashFetch in Server Component parent, pass data as propsPass Date/Map/functions to clientNot serializable across RSC boundarySerialize to string/plain object, or use Server ActionsFetch from own API in Server ComponentsUnnecessary round-trip — you're already on the serverAccess DB/service directlyWrap redirect()/notFound() in try-catchThey throw special errors that get swallowedCall outside try-catch or use unstable_rethrow()Skip loading.tsx or Suspense fallbacksUsers see blank page during data loadingAlways provide loading statesUse useSearchParams without SuspenseEntire page silently falls back to CSRWrap in \n
\n )\n}\n\n\nCritical gotcha: redirect(), notFound(), forbidden(), and unauthorized() throw special errors. Never catch them in try/catch:\n\n// BAD: redirect throw is caught — navigation fails!\ntry {\n await db.post.create({ data })\n redirect(`/posts/${post.id}`)\n} catch (error) {\n return { error: 'Failed' } // Catches the redirect too!\n}\n\n// GOOD: Call redirect outside try-catch\nlet post\ntry { post = await db.post.create({ data }) }\ncatch (error) { return { error: 'Failed' } }\nredirect(`/posts/${post.id}`)\n\nStreaming with Suspense\nexport default async function ProductPage({ params }: Props) {\n const { id } = await params\n const product = await getProduct(id) // Blocking — loads first\n\n return (\n Something went wrong!
\n \n\n
\n )\n}\n\nHooks That Require Suspense Boundaries\nHook\tSuspense Required\nuseSearchParams()\tAlways (or entire page becomes CSR)\nusePathname()\tIn dynamic routes\nuseParams()\tNo\nuseRouter()\tNo\nPerformance\nAlways use next/image over ...
\tFix invalid HTML nesting\nThird-party scripts modifying DOM\tUse next/script with afterInteractive\nSelf-Hosting\n\nSee self-hosting.md for Docker, PM2, cache handlers, and deployment checklist.\n\nKey points:\n\nUse output: 'standalone' for Docker — creates minimal production bundle\nCopy public/ and .next/static/ separately (not included in standalone)\nSet HOSTNAME=\"0.0.0.0\" for containers\nMulti-instance ISR requires a custom cache handler (Redis/S3) — filesystem cache breaks\nSet health check endpoint at /api/health\nNEVER Do\nNever\tWhy\tInstead\nAdd 'use client' by default\tBloats client bundle, loses Server Component benefits\tServer Components are default — add 'use client' only for interactivity\nMake client components async\tNot supported — will crash\tFetch in Server Component parent, pass data as props\nPass Date/Map/functions to client\tNot serializable across RSC boundary\tSerialize to string/plain object, or use Server Actions\nFetch from own API in Server Components\tUnnecessary round-trip — you're already on the server\tAccess DB/service directly\nWrap redirect()/notFound() in try-catch\tThey throw special errors that get swallowed\tCall outside try-catch or use unstable_rethrow()\nSkip loading.tsx or Suspense fallbacks\tUsers see blank page during data loading\tAlways provide loading states\nUse useSearchParams without Suspense\tEntire page silently falls back to CSR\tWrap in