Migrating from next-typesafe-url
What changes, what stays, and how the migration runs.
Coming from next-typesafe-url? You already know the problem space, and
the architecture barely moves: one definition file per route, a codegen
step, a typed path builder, hooks on both routers. What changes is the
vocabulary, the validation model — codecs that serialize as well as
parse, with any Standard Schema validator instead of required zod — and,
for some params, the URL wire format.
This section was written by migrating a real next-typesafe-url v6.1.0
app route by route; every step and claim in it was executed before being
documented.
What maps directly
- Route definition files —
routeType.tsbecomesroute.def.ts, zod schemas become codecs (concept map). - Path building —
$path({ route, ... })becomeshref(route, ...), with the route object replacing the string key. - Hooks — same names, new import, a discriminated result instead of
isLoading/isErrorflags. - Codegen — one CLI swaps for another, with a difference: paramour's is optional, and both can run side by side during the migration.
What changes on the wire
Your URLs will change
next-typesafe-url JSON-encodes object- and array-valued search
params into the query string. Paramour's default codecs write
conventional, human-readable params instead — which means existing
bookmarked or shared URLs with object-valued params stop parsing
unless you preserve the old encoding per key with p.json. Scalar
params carry over unchanged. See
the differences page
and the wire-format spec before you
start.
How this section is organized
- Concept map — every
next-typesafe-urlterm and its paramour equivalent, one table. - Step-by-step guide — the incremental migration: both libraries installed, one route at a time, remove the old library last.
- Differences — what behaves differently, what paramour deliberately doesn't have, and what you gain.
A codemod that automates the mechanical parts is planned; the manual path above is complete without it.