next-best-practices

In Next.js 15+, params and searchParams are Promises that must be awaited. Type them as Promise<{ slug: string }> and await them in pages, layouts, route handlers, and generateMetadata. Run npx @next/codemod@latest next-async-request-api to migrate automatically.

Props crossing the Server/Client boundary must be JSON-serializable, and Date objects lose their methods during serialization. Convert dates with .toISOString() on the server, then reconstruct with new Date() inside the client component.

Use Server Actions for mutations triggered from your own UI, such as form submissions, since they offer type safety and progressive enhancement. Use Route Handlers for webhooks, external API consumers, and public REST endpoints.

useSearchParams triggers a client-side rendering bailout in static routes unless wrapped in a Suspense boundary. Wrap the component using it in <Suspense> with a fallback so the rest of the page stays server-rendered.

Next.js 16 renames middleware.ts to proxy.ts, with the exported function renamed to proxy and config renamed to proxyConfig. The capabilities are identical, and the official upgrade codemod performs the rename automatically.

Hydration errors come from browser-only APIs, timezone-dependent dates, random values, or invalid HTML nesting. Gate browser APIs behind a mounted check, render dates on the client only, use useId for IDs, and fix invalid nesting like div inside p.