nextjs

description	Next.js routing with typed routes, PageProps, LayoutProps helpers, and nuqs for URL state. Use for pages, layouts, navigation, and query parameters.
name	nextjs
metadata	{"skiller":{"source":".agents/rules/nextjs.mdc"}}

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(): For specific app routes with exact typing
• useLayoutParams(): For layout components, returns all params as optional
• useLayoutParams(): 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

// 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 (

Product: {id}

Category: {category}

); }

// Layout with parallel routes export default function DashboardLayout(props: LayoutProps<'/dashboard'>) { return (

{props.sidebar} {/* Typed parallel route */} {props.children}

{props.analytics}

{/* Typed parallel route */}

); } // 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 }); }

// 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');

// 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

View Patient Browse Library

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

Blog Post router.push(('/blog/' + slug) as Route);

// ❌ TypeScript will catch invalid routes at compile time

Broken Link // ← Type error // 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 };

// ❌ 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