Daniel Saewitz

RFC: Next URL Validation

rigid UIsdrafted May 2025

The URL is Underrated

The URL has been called 'the OG state manager' and for good reason. But like all strings everywhere1, it's untyped and not-validated. Typing params and searchParams manually is a pain, wrapping the type in a Promise<> and then awaiting, validating, casting that data in pages feels unnecessary and very awkward.

I think it's possible to make the URL typed, validated, and casted. And in doing-so, the URL becomes more enticing to utilize. I have some ideas.

The Ideas

Inspiration could come from nuqs and tanstack router2 which both deeply understand the importance of URLs and make it a rich environment to interact with. This would make the URL, which is currently a first-class untyped string interface into a fundamentally typed interface, with better dx ergonomics.

The idea here is to have more rigid and durable URLs, and be able to manipulate them through a more powerful interface. Through these ideas, it encourages people to move state into URLs, giving UIs more object permanence. Developers overuse in-memory client-side state (useState). By making these APIs available natively, next.js can make the web become a more stable and rigid platform.

The big caveat here is that I don't know or understand the internals of next.js, nor am I an expert at complex typescript. I don't know if what I suggest here is possible or feasible, only that the general dx would be ideal for me (maybe not for others!). Let's take a look:

1export const schema = z.object({
2  searchParams: z.object({
3    uuid: z.string().max(255),
4    query: z.string().max(255),
5  }),
6  params: z.object({
7    id: z.coerce.number(),
8  }),
9});
10
11export async function validate(params: any, searchParams: any) {
12  return schema.parse({ params, searchParams });
13}
14
15export default function Page({ searchParams }) {
16  // searchParams is typed and unwrapped
17  // if we want to skip automatic unwrapping, we could
18  // await searchParams(); // just like headers()
19
20} // ...
21
22// or next.js could expose a createPage function that accepts the validation and a second param with the render function if this typing is not feasible
23// this could also be implemented in user-land (but you lose some stuff): Some discussion on that here w/ Francois https://github.com/47ng/nuqs/discussions/446#discussioncomment-13204177

Preferably, validation should support Standard Schema so users can bring their own validation library. It's unclear if these should live next to pages or layouts, or otherwise. Later on I explain why this may be better moved to its own file (validation.ts).

If a URL does not pass the validation, next should return a 400 (or similar) with a message indicating the URL params were invalid3. This encourages developers to be more intentional with their URLs and provide strong safety for these generally untyped strings.

Ideally, leafier components could look up the tree to pull out the validation4. And client components could use useSearchParams to return a raw (typed) object (rather than the current URLSearchParams that requires .get). This is one of those rare scenarios where leaning on web standards is actually more awkward dx.

A new (nuqs inspired) state getter/setter could be introduced to manage searchParams akin to useState (again relying on the underlying validation):

1function ClientComponent() {
2  // if the searchParams can be pulled from the page level
3  // we don't need to keep declaring them everywhere
4  const [searchParams, setSearchParams] = useSearchParams({
5    history: 'push', // inspired by nuqs
6    shallow: true, // default to shallow routing
7  });
8}
9

Links could be be fully typed and accept objects:

1<Link href={{ pathname: '/user/[id]', params: { id: 1 }}>
2  User Profile
3</Link>

or

1<Link href={{ pathname: '/search', query: { q: '' }} shallow>
2  Reset Search Query
3</Link>

Shallow indicates client-only routing (vs. going to the server), again inspired by nuqs.

of course the same in router:

1router.redirect({ href: { pathname: '/search', query: { q: 'Search Query' } } });

It might be worth taking this time to unify the naming across searchParams and query, doesn't really matter which one, but would be better if it was consistent. I know this probably comes from the location./href standard, but perhaps would be better to have consistency.

Developer Story

If you're still with me – let's walk through a developer story. We're creating a search page that data fetches on the server and then filters on the client.

So we start with a page:

1export default async function Page() {
2  const data = await fetchData();
3
4  return <ClientSearch data={data} />
5}

and our client search:

1'use client';
2
3export function ClientSearch({ data }) {
4  const [value, setValue] = useState('');
5
6  const onChange = (e) => setValue(e.target.value);
7
8  return (
9    <div>
10      <input onChange={onChange} value={value} />
11      {data.filter(item => item.name.includes(value))
12        .map(item => <Item item={item} key={item.id} />)}
13    </div>
14  );
15}

This would be better if the query was in the URL, but fine enough. This is how 95% of React devs would solve it.

Let's say our data on the server is actually much larger than we can send on the client. Let's add the new URL validation and do our data processing on the server:

1export const schema = z.object({
2  searchParams: z.object({
3    q: z.string().max(255),
4  }),
5});
6
7export async function validate(params: any, searchParams: any) {
8  return schema.parse({ params, searchParams });
9}
10
11export default async function Page({ searchParams }) {
12  const data = await fetchData({ query: searchParams.q });
13
14  return (
15    <div>
16      <SearchInput />
17      {data.filter(item => item.name.includes(value))
18        .map(item => <Item item={item} key={item.id} />)}
19    </div>
20  );
21}

We could adjust these components to add suspense boundaries/transitions if we wanted.

and SearchInput:

1'use client';
2
3export function SearchInput() {
4  // ---> [typed]
5  const [searchParams, setSearchParams] = useSearchParams({
6    history: 'replace',
7    shallow: false,
8  });
9
10  //  ---------------------------------->   [this is now typed!]
11  const onChange = (e) => setSearchParams({ q: e.target.value });
12
13  return (
14    <input onChange={onChange} value={value} />
15  );
16}

Another Example - More Server Processing

Let's go back to our Client-Side example and add server-side pagination (how an average react dev would do it):

1// ----------------------------------------------> we have to manually type searchParams
2//                                                 and it's awkward and crufty and doesn't
3//                                                 actually do anything at runtime
4export default function Page({ searchParams }: { searchParams: Promise<{ page: string }> }) {
5  const { page } = await searchParams;
6  // this gets awkward, we need to cast page to a number (and we forgot to validate it)
7  const pageNumber = Number(page); // this is hacky/crumbly
8  const data = await fetchData({ page: pageNumber }); // we have two variables in context, it's getting messy
9
10  return <ClientSearch data={data} page={pageNumber} />
11}

and

1'use client';
2
3export function ClientSearch({ data, page }) {
4  const router = useRouter();
5  const [value, setValue] = useState('');
6
7  const onChange = (e) => setValue(e.target.value);
8  const onPageChange = (nextPage: number) => router.push('/search?page=' + page);
9
10  return (
11    <div>
12      <input onChange={onChange} value={value} />
13      {data.filter(item => item.name.includes(value))
14        .map(item => <Item item={item} key={item.id} />)}
15      <Pagination page={page} onPageChange={onPageChange} />
16    </div>
17  );
18}

Alright this code has gotten pretty messy. What if we had all the primitives we designed above? Let's go back to our more complex example:

1export const schema = z.object({
2  searchParams: z.object({
3    q: z.string().max(255),
4    page: z.number().min(1).catch(1), // ooo! validation!
5  }),
6});
7
8export async function validate(params: any, searchParams: any) {
9  return schema.parse({ params, searchParams });
10}
11
12// ----------------------->  [typed+casted]!
13export default function Page({ searchParams }) {
14  const data = await fetchData({ query: searchParams.q, page: searchParams.page });
15
16  return (
17    <div>
18      <SearchInput />
19      {data.filter(item => item.name.includes(value))
20        .map(item => <Item item={item} key={item.id} />)}
21      <ClientPagination page={searchParams.page} />
22    </div>
23  );
24}

and ClientPagination:

1'use client';
2
3export function ClientPagination({ page }: { page: number }) {
4  const [searchParams, setSearchParams] = useSearchParams({
5    history: 'push',
6    shallow: false,
7  });
8
9  const prevPage = (e) => setSearchParams({ page: Math.max(1, page - 1) });
10  const nextPage = (e) => setSearchParams({ page: page + 1 });
11
12  return (
13    <>
14      <Button onClick={prevPage}>Prev</Button> // or even better, these could be links ofc
15      {page}
16      <Button onClick={nextPage}>Next</Button>
17    </>
18  );
19}

And then when searching, make sure we reset page to 15:

1'use client';
2
3export function SearchInput() {
4  const [searchParams, setSearchParams] = useSearchParams({
5    history: 'replace',
6    shallow: false,
7  });
8
9  // reset page to 1 on query change
10  const onChange = (e) => setSearchParams({ q: e.target.value, page: 1 });
11
12  return (
13    <input onChange={onChange} value={value} />
14  );
15}

That all feels a lot simpler and more rigid. There could be an individual useSearchParam hook introduced like nuqs (akin to useQueryState - perhaps a better name), though the bulkier one seems decent to me.

Validation.ts?

If validation was moved to its own isomorphic file (validation.ts) we could run validation on the client and the server and get rid of { page: Math.max(1, page - 1) } if we tried to switch it to page=>0 zod would reject it on the client and keep the page at 1 minimum. It could even be used in the buttons to run future-validation with some more magic:

1const [searchParams, setSearchParams, validateSearchParams] = useSearchParams({
2  history: 'replace',
3  shallow: false,
4});
5
6<Button onClick={prevPage} disabled={!validateSearchParams({ page: page - 1 })}>Prev</Button>

Concerns+Thoughts

The url is a messy place. Affiliate tracking, referrals, etc. could break. So it probably is best to not validate unlisted search params (or to strip them). If it's possible to detect the default (or empty) search params, we could strip the URL leading to cleaner URLs (tanstack does this I believe).

Personally I find the having-to-await searchParams and params kind of annoying. I believe it's done because you want a heuristic to identify dynamic vs. static pages, but naively I don't know if that's the best heuristic. There are async pages that are intended to be static: like a blog post6. I'm sure there are more reasons than that alone, so if it's truly better then that's okay.

I think if these changes were to be implemented, you could get rid of searchParams passed as props and have them be accessible in any server component (except for layouts? so sub-page maybe?) via await searchParams() - which would return typed searchParams. And useSearchParams for client components. Less prop drilling and less manual typing (that doesn't actually do anything).

I think a framework like next should embrace the URL as the powerful thing that it is, and I think providing a more natural dx surrounding it will lead to more people taking advantage of the URL (and thereby the server). Nothing here is specific to RSCs, but it does improve ergonomics. The URL is the thing that give our UIs permanence (sharing links, visiting via history) and developers should be encouraged to place (some) state there. When state is placed inside useState calls, those states are lost when the tab closes.

Final hot take: Though it's a different situation, useState reminds me of the trend useEffect has gone, in that once people see different ways to store state (the url), we'll see it less abused and overused. I'm surprised how rarely I reach for useState these days, choosing to stick things in the URL when appropriate. Server or client.

Thanks for reading. Happy to answer any questions.