/next-typesafe-url

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

Primary LanguageTypeScriptMIT LicenseMIT

next-typesafe-url

Now with full support for app directory and server components!

next-typesafe-url-example

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