Next.js Routing & Navigation

Requirements

Route Props Helpers (Next.js 15.5+)

• Use globally available PageProps, LayoutProps, RouteContext types - no imports needed
• RouteContext: Use for typing route handler context parameters with proper type inference
• PageProps: Use for page components with typed params and searchParams
• LayoutProps: Use for layout components with children and parallel route slots
• Automatically includes typed params, searchParams, children, and parallel route slots
• Always await Promise-based params and searchParams

Typed Routes (Next.js 15.5+)

• TypeScript will catch invalid routes in <Link> components at compile time
• Automatically generates types based on your file structure
• Use Route type for props
• Use as Route for non-literal strings (e.g., ('/blog' + slug) as Route)

Custom Param Hooks

• NEVER use useParams from Next.js directly - use typed alternatives from @/hooks/use-params
• Use unique param names (e.g., [userId] not [id]) for better type inference
• useTParams<Route>(): For specific app routes with exact typing
• useLayoutParams(): For layout components, returns all params as optional
• useLayoutParams<Route>(): For layout components with route prefix, exact route params required + prefix params optional

URL Query State

• NEVER use useSearchParams from Next.js - always use nuqs for URL query state
• Use appropriate parsers based on parameter data type
• Configure history mode and clearOnDefault
• Handle URL updates with void to prevent promise-related linting issues

Examples

<example> // Page component with PageProps export default async function Page(props: PageProps<'/products/[category]/[id]'>) { const { category, id } = await props.params; const searchParams = await props.searchParams;

return ( <div> <h1>Product: {id}</h1> <p>Category: {category}</p> </div> ); } </example>

<example> // Layout with parallel routes export default function DashboardLayout(props: LayoutProps<'/dashboard'>) { return ( <div className="dashboard"> <aside>{props.sidebar}</aside> {/ Typed parallel route /} <main>{props.children}</main> <div>{props.analytics}</div> {/ Typed parallel route /} </div> ); } </example>

<example> // Route handler with RouteContext (recommended) export async function GET( request: Request, ctx: RouteContext<'/api/posts/[slug]'> ) { const { slug } = await ctx.params; return Response.json({ slug }); }

// Multiple parameters export async function DELETE( request: Request, ctx: RouteContext<'/api/users/[id]/posts/[postId]'> ) { const { id, postId } = await ctx.params; return Response.json({ userId: id, postId }); }

// Optional parameters export async function PUT( request: Request, ctx: RouteContext<'/api/categories/[[...slug]]'> ) { const { slug } = await ctx.params; // slug: string[] | undefined return Response.json({ segments: slug }); } </example>

<example> // URL Query State with nuqs export const useFilterState = () => { return useQueryState( 'filter', parseAsStringEnum(['all', 'active', 'completed']) .withDefault('all') .withOptions({ history: 'push', clearOnDefault: true }) ); };

// Usage const [filter, setFilter] = useFilterState(); void setFilter('active'); </example>

<example> // Enable Typed Routes in next.config.ts const nextConfig = { typedRoutes: true, // Compile-time type safety for routes }; export default nextConfig;

// Usage in components import Link from 'next/link';

// ✅ Type-safe links

<Link href="/patients/123">View Patient</Link> <Link href="/library/dx-tx?category=cardiology">Browse Library</Link>

// ✅ Non-literal strings with Route type const slug = 'nextjs';

<Link href={('/blog/' + slug) as Route}>Blog Post</Link> router.push(('/blog/' + slug) as Route);

// ❌ TypeScript will catch invalid routes at compile time

<Link href="/invalid-route">Broken Link</Link> // ← Type error </example>

<example> // Custom Param Hooks Usage import { useTParams, useLayoutParams } from '@/hooks/use-params';

// ✅ For specific routes with exact typing const PatientPage = () => { const params = useTParams<'/patients/[patientId]'>(); params.patientId; // string - guaranteed to exist };

// ✅ For layouts - all params optional const RootLayout = ({ children }) => { const params = useLayoutParams(); params.patientId; // string | undefined params.complaintId; // string | undefined };

// ✅ For layouts with route prefix - exact + optional const ComplaintLayout = ({ children }) => { const params = useLayoutParams<'/complaints/[complaintId]'>(); params.complaintId; // string - required for exact match params.someOtherParam; // string | undefined - from related routes }; </example>

<example type="invalid"> // ❌ Don't use manual typing for route handlers export async function GET( request: Request, { params }: { params: Promise<{ slug: string }> } ) { const { slug } = await params; return Response.json({ slug }); }

// ❌ Don't use manual typing for page props interface Props { params: Promise<{ slug: string }>; children: React.ReactNode; }

// ❌ Don't use raw useParams - use typed alternatives import { useParams } from 'next/navigation'; const params = useParams();

// ❌ Don't use useSearchParams import { useSearchParams } from 'next/navigation'; const searchParams = useSearchParams();

// ❌ Don't use string concatenation for routes router.push(/patients/${id}); // Use typed routes instead </example>