next-safe-navigation

In Server Components, do not attempt to manually type params or searchParams in your page props. Because schemas can transform values (e.g., coercing a string to a number), you should treat them as unknown and use the generated $parseParams or $parseSearchParams methods to get validated, typed data.

Methods:

• routes.<routeName>.$parseParams(params): Validates dynamic route segments.
• routes.<routeName>.$parseSearchParams(searchParams): Validates query string parameters.

// src/app/customers/page.tsx
import { routes } from "@/shared/navigation";

interface CustomersPageProps {
  // ✅ Never assume the types of your params before validation
  searchParams?: unknown
}

export default async function CustomersPage({ searchParams }: CustomersPageProps) {
  const { query, page } = routes.customers.$parseSearchParams(searchParams);

  const customers = await fetchCustomers({ query, page });

  return (
    <main>
      <input name="query" type="search" defaultValue={query} />
      <Customers data={customers} />
    </main>
  )
};

// src/app/invoices/[invoiceId]/page.tsx
import { routes } from "@/shared/navigation";

interface InvoicePageProps {
  // ✅ Never assume the types of your params before validation
  params?: unknown
}

export default async function InvoicePage({ params }: InvoicePageProps) {
  const { invoiceId } = routes.invoice.$parseParams(params);

  const invoice = await fetchInvoice(invoiceId);

  return (
    <main>
      <Invoice data={invoice} />
    </main>
  )
};

Use the provided hooks to access validated route parameters and search parameters in Client Components.

Hooks:

• useSafeParams(<routeName>): Returns the validated params for the specified route.
• useSafeSearchParams(<routeName>): Returns the validated searchParams for the specified route.

// src/app/customers/page.tsx
'use client';

import { useSafeSearchParams } from "@/shared/navigation";

export default function CustomersPage() {
  const { query, page } = useSafeSearchParams('customers');

  const customers = useSuspenseQuery({
    queryKey: ['customers', { query, page }],
    queryFn: () => fetchCustomers({ query, page}),
  });

  return (
    <main>
      <input name="query" type="search" defaultValue={query} />
      <Customers data={customers.data} />
    </main>
  );
}

// src/app/invoices/[invoiceId]/page.tsx
'use client';

import { useSafeParams } from "@/shared/navigation";

export default function InvoicePage() {
  const { invoiceId } = useSafeParams('invoice');

  const customers = useSuspenseQuery({
    queryKey: ['invoices', { invoiceId }],
    queryFn: () => fetchInvoice(invoiceId),
  });

  return (
    <main>
      <Invoice data={customers.data} />
    </main>
  );
}

Use createNavigationConfig to define your application's route structure in a single location. This function accepts a callback that provides a defineRoute helper. You can define params for dynamic segments and search for query string parameters using a validation schema.

Tip: Enable experimental.typedRoutes in next.config.js for improved autocomplete experience.

// src/shared/navigation.ts
import { createNavigationConfig } from 'next-safe-navigation';
import { z } from 'zod';

export const { routes, useSafeParams, useSafeSearchParams } =
  createNavigationConfig((defineRoute) => ({
    home: defineRoute('/'),
    customers: defineRoute('/customers', {
      search: z
        .object({
          query: z.string().default(''),
          page: z.coerce.number().default(1),
        })
        .default({ query: '', page: 1 }),
    }),
    invoice: defineRoute('/invoices/[invoiceId]', {
      params: z.object({
        invoiceId: z.string(),
      }),
    }),
    shop: defineRoute('/support/[...tickets]', {
      params: z.object({
        tickets: z.array(z.string()),
      }),
    }),
    shop: defineRoute('/shop/[[...slug]]', {
      params: z.object({
        // ⚠️ Remember to always set your optional catch-all segments
        // as optional values, or add a default value to them
        slug: z.array(z.string()).optional(),
      }),
    }),
  }));

Use makeRouteBuilder to define a route with its associated path parameters and search parameters using Standard Schema (e.g., Zod, Valibot, ArkType). This creates a function that, when called with validated inputs, returns a correctly formatted URL string.

Key Behaviors:

• Path Parameters: If your path contains dynamic segments like [id] or catch-all segments like [[...slug]], you must provide a params schema in the schemas object. If you omit it, the function will throw a runtime error: Validation missing for path params: "/your-path".
• Search Parameters: You can optionally provide a search schema to validate and include URL search parameters.
• Next.js Integration: The builder respects Next.js Route types. If experimental.typeRoutes is enabled in your Next.js config, the builder will provide autocomplete for your available routes.
• Return Value: The resulting function returns a string representing the full URL (including the query string if search parameters are provided).

import { makeRouteBuilder } from 'next-safe-navigation';
import { z } from 'zod';

// 1. Define the route builder
const productRoute = makeRouteBuilder(
  '/products/[id]',
  {
    params: z.object({ id: z.string() }),
    search: z.object({ color: z.string().optional() }),
  }
);

// 2. Use the builder to generate a URL
const url = productRoute({ 
  id: '123', 
  search: { color: 'red' } 
});
// Returns: "/products/123?color=red"