next-typesafe-url

Now with full support for app directory and server components!

Fully typesafe, JSON serializable, and zod validated URL search params, dynamic route params, and routing for NextJS.

Big shoutout to tanstack/router and yesmeck/remix-routes for inspiration and ideas.

Whats wrong with curent solutions?

Routing

Next.js's non-typesafe routing can lead to runtime errors and make it difficult to catch routing-related issues during development, as it relies on string literals instead of type-safe constructs.

Search Params

from tanstack/router:

Traditional Search Param APIs usually assume a few things:

• Search params are always strings
• They are mostly flat
• Serializing and deserializing using URLSearchParams is good enough (Spoiler alert: it's not, it sucks)

Typesafety Isn’t Optional

How does next-typesafe-url solve these problems?

• Fully typesafe routing- all the way from the route, to the route params, to the search params
• Search params are JSON-first, so you can pass strings, numbers, booleans, nulls, and even nested objects and arrays
• Search and route params are validated at runtime using zod, so you can be sure that the data you get matches the schema you expect

Installation

npm install next-typesafe-url
# or
yarn add next-typesafe-url
# or
pnpm add next-typesafe-url

Usage

PLEASE READ THE DOCS

Issues

Please open an issue if you find a bug or have a feature request. You can also DM me on twitter @ethanniser with any questions or concerns.

Contributing

All contributions are welcome! Please open an issue or submit a PR.

License

MIT

TODO

• 100% test coverage
• remix-routes style typescript plugin to improve autocomplete and add 'go to definition' to route string (would take you to the route file)