next-typesafe-url is a TypeScript library for Next.js that makes URL search params, dynamic route params, and routing fully typesafe, JSON-serializable, and validated at runtime with zod.
What is next-typesafe-url?
next-typesafe-url is an open-source TypeScript library for Next.js that solves the problem of non-typesafe routing and URL state. It takes zod schemas for your route and search parameters and produces typed, validated data at runtime. The library runs inside Next.js applications and supports both the app directory and server components, as stated in the README. It was created by Ethan Niser (Twitter: @ethanniser) and is available on npm under the MIT license.
Key Features
- Fully typesafe routing — Type safety flows from the route definition to the route params and search params, eliminating errors caused by string-literal URLs.
- JSON-serializable search params — Instead of only strings, you can pass strings, numbers, booleans, nulls, nested objects, and arrays through URL search params.
- Zod runtime validation — Search and route params are validated at runtime with zod, so the data your app receives always matches the schema you defined.
- App directory and server components support — The library explicitly supports Next.js's app router and server components, a feature highlighted at the top of the README.
- Inspired by tanstack/router and remix-routes — The project credits these libraries for influencing its design, though next-typesafe-url is built specifically for Next.js.
- Simple installation — Install via npm, yarn, or pnpm with a single command:
npm install next-typesafe-url.
- Open source under MIT — The source code is available on GitHub, and contributions are welcome through issues or pull requests.
Who is it for?
- Next.js developers using TypeScript — They get end-to-end type safety for routing and URL parameters, reducing runtime errors during development.
- Teams building complex apps with dynamic routes — They can define zod schemas for route params so that every dynamic segment is validated and typed.
- Developers who need to pass nested data through URLs — Because search params are JSON-serializable, they can encode objects and arrays without manual stringification.
What can you do with next-typesafe-url?
- Share complex UI state via URLs — Pass nested objects and arrays as search params, enabling shareable filter states, pagination, or form data.
- Validate incoming route params — Zod schemas guarantee that a dynamic route like
/user/[id] receives an id that matches the expected type and shape.
- Build typed navigation — Use the library's routing helpers to create links that are checked at compile time, avoiding typos in
href strings.
Pricing
next-typesafe-url is free and open source, released under the MIT license. You can use it in commercial and personal projects without restrictions.
FAQ
Does next-typesafe-url work with the Next.js app router?
Yes. The README states the library now has full support for the app directory and server components.
What data types can I use in search params?
Any JSON-serializable value: strings, numbers, booleans, nulls, nested objects, and arrays. This is a core feature that goes beyond the standard string-only search param APIs.
How does runtime validation work?
You define a zod schema for your route and search parameters. At runtime, the library validates incoming URL data against that schema and returns the typed, validated result.
How do I install next-typesafe-url?
Run npm install next-typesafe-url, yarn add next-typesafe-url, or pnpm add next-typesafe-url in your Next.js project.
Is there a TypeScript plugin available?
Not yet. The project's TODO list includes a remix-routes-style TypeScript plugin to improve autocomplete and add "go to definition" for route strings, but it hasn't been implemented.
