Concept Map

Same architecture, different vocabulary. Both libraries put a definition file next to each route, run a codegen step, build links through a typed helper, and read params through hooks. This table translates the whole surface; the sections after it expand the three mappings that aren't one-to-one renames.

Code on the left is next-typesafe-url v6.1.0, shown as plain (uncompiled) snippets. Code on the right is live — compiled against the paramour packages on every docs build.

The map

Three rows deserve honesty up front. withParamValidation has no replacement wrapper — migrating means adding a parse call inside the page, which the guide walks through. App Router hooks have no isLoading arm — if your components branch on it, that branch becomes dead code (see differences). And the JSON-blob URL format survives only where you opt into p.json per key (see differences).

Schemas become codecs

The one mapping that isn't a rename. A zod schema validates; a codec validates and owns the wire format — how the value is written into the URL and read back out. Your zod schemas don't disappear: they slot into codecs as refinements, because paramour accepts any Standard Schema validator.

Before, with next-typesafe-url:

import { type DynamicRoute } from "next-typesafe-url";
import { z } from "zod";

export const Route = {
  routeParams: z.object({
    productID: z.number(),
  }),
  searchParams: z.object({
    location: z.enum(["us", "eu"]).optional(),
    userInfo: z.object({
      name: z.string(),
      age: z.number(),
    }),
  }),
} satisfies DynamicRoute;
export type RouteType = typeof Route;

After, with paramour:

import { defineAppRoute, p } from "paramour";
import { z } from "zod";

export const productRoute = defineAppRoute("/product/[productID]", {
  params: { productID: p.number() },
  search: {
    location: p.enum(["us", "eu"]).optional(),
    userInfo: p.json(z.object({ name: z.string(), age: z.number() })),
  },
});

declare const props: import("paramour").RouteProps;
const { search } = await productRoute.parse(props);
         
const search: InferSearchOutput<{
    readonly location: Codec<"us" | "eu", "optional", false, "single", boolean>;
    readonly userInfo: Codec<{
        name: string;
        age: number;
    }, "required", false, "single", boolean>;
}>

Each codec states its own wire behavior: p.number() parses the segment with a strict grammar, p.enum writes the member string, p.json keeps the zod object JSON-encoded exactly like the old library did. The codecs concept page covers the full model.

Validation becomes parsing

withParamValidation wrapped your page so validated props arrived from outside. Paramour has deliberately no wrapper: parsing is a call you make inside the component, which is also why the halves (parseParams, parseSearch) and the safe* twins exist — you choose the surface and the failure mode at the call site.

Before:

import { withParamValidation } from "next-typesafe-url/app/hoc";
import type { InferPagePropsType } from "next-typesafe-url";
import { Route, type RouteType } from "./routeType";

type PageProps = InferPagePropsType<RouteType>;

async function Page({ routeParams, searchParams }: PageProps) {
  const { productID } = await routeParams;
  // ...
}

export default withParamValidation(Page, Route);

After:

// @filename: app/product/[productID]/route.def.ts
import { defineAppRoute, p } from "paramour";

export const productRoute = defineAppRoute("/product/[productID]", {
  params: { productID: p.number() },
});

// @filename: app/product/[productID]/page.tsx
import type { RouteProps } from "paramour";

import { productRoute } from "./route.def";

export default async function Page(props: RouteProps) {
  const { params } = await productRoute.parse(props);
  return <h1>Product {params.productID}</h1>;
}

The routes reference lists every parse surface and when to reach for each.

Errors: ZodError becomes issues

Where next-typesafe-url handed you a raw ZodError, every paramour failure is a ParamourError subclass carrying a flat issues array — every bad key reported at once, the same shape on the server, in hooks, and in standalone decoding.

Before:

const { data, isLoading, isError, error } = useSearchParams(Route.searchParams);
// error: z.ZodError | undefined

After:

import { defineAppRoute, p } from "paramour";

const route = defineAppRoute("/product/[id]", { params: { id: p.integer() } });

declare const props: import("paramour").RouteProps;
const result = await route.safeParse(props);
if (result.status === "error") {
  result.error.issues;
                
issues: readonly Issue[]
}

The errors reference documents the hierarchy.

Ready to move code? The step-by-step guide migrates a real app one route at a time.