DEV Community: Lei Wang

Three Design Decisions I Reversed While Building a React Hook

Lei Wang — Thu, 05 Nov 2026 15:13:27 +0000

Introduction

In my previous post I introduced @standard-search-params/react, a React hook that validates URL search params against any Standard Schema library. This post is about three decisions I changed my mind on while building v0.2.0.

It isn't a story about a clean design arriving fully formed. It's a record of where my first idea was wrong and why I changed it, in case it's useful to anyone else building a small library.

A note on process: I used AI (Claude and Claude Code) for design discussion and code review. Everything below is something I could confirm in the implementation and the tests.

Background: how the hook behaves

The hook reads the URL search params once, on mount, and validates each one against its own schema.

const schema = {
  page: z.coerce.number().int().min(1),
  q: z.string().min(1),
};

const { validatedSearchParams, refresh } = useStandardSearchParams(schema);

v0.2.0 added a listenToPopstate option and a refresh() function for re-reading the URL after it changes. Building those two things is what led to the three reversals below.

1. "Wrap your schema in useMemo" fixed nothing

Context

Sometimes the set of schema keys changes at runtime, for example when only admin users should have an extra param validated. Because the hook only reads the URL on mount, keys added later are silently ignored. I decided to add a development warning so the problem would be noticed early.

My first idea had two holes

My first idea was to warn whenever the schema's reference changed, and to tell people in the docs to "memoize your schema with useMemo".

Hole 1: it would fire constantly. The README says it's fine to write the schema inline in the component. An inline schema gets a new reference on every render, so a reference check would warn on the very pattern I recommend. A warning that fires every time is a warning nobody reads.

So I compare the set of keys instead of the reference:

const schemaKeys = Object.keys(schema).sort().join(',');
const prevSchemaKeysRef = useRef(schemaKeys);

useEffect(() => {
  if (isDev && prevSchemaKeysRef.current !== schemaKeys) {
    console.warn(/* ... */);
    prevSchemaKeysRef.current = schemaKeys;
  }
}, [schemaKeys]);

Now an inline schema (same keys, new reference) stays quiet, and only a real change in the key set warns.

Hole 2: useMemo doesn't fix anything. This was the more important one. The hook's initial read runs in an effect on mount, once. Stabilizing the schema's reference with useMemo never triggers a re-parse. useMemo only guarantees that the reference stays the same. It has no effect like "re-read when the contents change".

So "use useMemo" was advice that looked like a fix and fixed nothing.

The correct fix is to remount the component:

<SearchResults key={isAdmin ? 'admin' : 'user'} />

The warning message says so:

useStandardSearchParams: schema keys changed after mount (was [page], now [page,q]),
but this hook only reads the URL once, on mount, so the new keys won't be read.
If the set of keys genuinely needs to change at runtime, remount the component
(e.g. with a `key` prop) — memoizing the schema object does not cause a re-parse.

Two implementation mistakes too

A Rules of Hooks violation. My first version called the hooks inside a condition: if (isDev) { useRef(...); useEffect(...) }. Even if the value is fixed at build time, writing it that way fails react-hooks/rules-of-hooks. The hooks are called unconditionally, and the isDev check lives inside the effect.
Checking that process exists. A bare process.env.NODE_ENV throws a ReferenceError in environments without a bundler. Check typeof process !== 'undefined' first.

const isDev =
  typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';

What I took from it

Before writing a fix into a warning or a doc, check that it actually works in the implementation. Here that was a matter of looking at an effect's dependency array.

This warning also has a limit. If the keys stay the same but a validator's contents change (say max(5) becomes max(10)), it can't tell. Standard Schema's internals differ between libraries, so comparing contents in a general way isn't realistic, and I decided to accept that gap.

2. I didn't turn popstate on by default

The popstate event fires when the user presses the browser's back or forward button. My first plan was to listen for it by default: it's a native API, the listener is cheap, and the side effects seemed small.

What changed my mind was consistency with the library's own design.

The core of this hook is predictable behavior: the URL is read once, on mount.
The README, the docstrings, and the warning above are all written on that premise.
Turning popstate on by default means "values change by themselves when you press back" would apply to existing users too. The API doesn't break, but the behavior changes without telling anyone.

So it's off by default, and you opt in explicitly:

const { validatedSearchParams } = useStandardSearchParams(schema, {
  listenToPopstate: true,
});

One more detail. SPA router navigation such as router.push() or navigate() only pushes a history entry, and it doesn't fire popstate. So listenToPopstate doesn't cover that case either. For that, call refresh() whenever the router's location changes:

// Next.js example
const { validatedSearchParams, refresh } = useStandardSearchParams(schema);
const pathname = usePathname();
const searchParams = useSearchParams();

useEffect(() => {
  refresh();
}, [pathname, searchParams, refresh]);

3. `refresh()` deduplication created a "silently does nothing" case

Context

On a back navigation, both the popstate listener and a refresh() call from the router's effect can fire for the same navigation. Parsing twice is wasteful, so I made refresh() return early when location.search is the same as the last one it read.

The problem

That deduplication had a side effect I missed. If the URL is the same but the schema's rules have changed and you want to re-validate, refresh() is silently ignored.

The name refresh() suggests "read again when I call it." Silently doing nothing because of an internal optimization doesn't match what the name promises.

The options

(a) Document that it only has an effect when the URL changes
(b) Add a flag to force it

I chose (b). A mismatch between a name and its behavior should be fixed in the design, not papered over in the docs. The deduplication exists to serve the automatic popstate listener. An explicit call to refresh() is entitled to an escape hatch.

if (!refreshOptions?.force && lastSearchRef.current === currentSearch) {
  return;
}

refresh({ force: true }); // re-validate against the current schema even if the URL is the same

The default stays "no force." If you call refresh() on every router navigation, many navigations leave the query string unchanged, and re-validating each time would be wasteful. Only the unusual case, where you want to re-read the same URL, requires you to opt in.

The tests pin this behavior down: with the same URL and a changed schema, no force is ignored and force: true takes effect.

Two smaller fixes in the implementation

The useMemo on the return value. In my design draft, the return value had turned back into a plain object literal. That returns a new reference on every render and breaks the existing test that checks referential stability. I went back to wrapping it in useMemo.

  return useMemo(() => ({ ...state, refresh: parse }), [state, parse]);

Merging state into one useState. Keeping isSearchParamsReady in a separate useState means two setState calls per parse(). React 18 batches them automatically, but this library's peerDependencies allow react >=16.8. In React 17 and earlier, a setState called from a native event like popstate isn't batched, so it can cause two re-renders. Putting the values in a single state object makes it one setState call.

Wrapping up

These three changes share a way of thinking:

Don't silently change behavior, and don't silently do nothing. That's why popstate isn't on by default and why refresh() doesn't quietly ignore a call.
Check that the fix works before writing it down. The useMemo advice is the example.
Fix a mismatch between a name and its behavior in the design, not in the docs. refresh({ force: true }) is the example.

When adding features, I want to keep checking that I'm not breaking what existing users already expect from the library.

Next time, I plan to write about how I worked on this with AI, including how design discussion and code review were split up.

Japanese version (日本語版) is available on Zenn: https://zenn.dev/wdp/articles/ece2138453fb9a

Why I Built @standard-search-params/react Around Standard Schema

Lei Wang — Mon, 21 Sep 2026 12:13:43 +0000

Introduction

Have you ever written code like this to handle URL search params in React?

const searchParams = new URLSearchParams(window.location.search);
const page = Number(searchParams.get('page')) || 1;
const q = searchParams.get('q') || '';

It's simple, but writing this over and over as your app grows gets tedious. And the fallback behavior for an invalid value (like page=abc) tends to differ depending on who wrote the code.

A number of libraries already tackle this by combining a validation library like Zod with URL params. @standard-search-params/react takes the same approach, but it's built around a spec called Standard Schema instead of any single validation library.

npm install @standard-search-params/react

What is Standard Schema?

Standard Schema is a spec that lets different validation libraries — Zod, Valibot, ArkType, and others — expose a common interface. It's intentionally minimal: a validator just needs a ~standard property with a shared validate() method.

What makes this useful is that library authors no longer need to build separate integrations for Zod, Valibot, and so on. Build one tool against Standard Schema, and it works the same way regardless of which validator your consumers happen to use.

@standard-search-params/react is built so it works with any Standard Schema-compliant validator.

import { z } from 'zod';
import { useStandardSearchParams } from '@standard-search-params/react';

const schema = {
  page: z.coerce.number().int().min(1),
  q: z.string().min(1),
};

function SearchResults() {
  const { validatedSearchParams, isSearchParamsReady } =
    useStandardSearchParams(schema);

  if (!isSearchParamsReady) return null;

  return <div>page: {validatedSearchParams.page ?? 1}</div>;
}

If you'd rather use Valibot, swap z.coerce.number() for v.pipe(v.string(), v.transform(Number)) — the hook itself doesn't change at all. You can even mix Zod and Valibot in the same schema object.

import { z } from 'zod';
import * as v from 'valibot';

const schema = {
  page: z.coerce.number().int(),
  q: v.pipe(v.string(), v.minLength(1)),
};

Why per-field schemas instead of one big object schema?

Most validation hooks for URL params validate the whole query string against a single object schema. That approach has a weakness: one invalid field can invalidate everything.

?page=2&q=hello&sort=bad

If sort holds an unexpected value here and you're validating the whole object as one schema, a perfectly valid page and q can get thrown out along with it.

@standard-search-params/react avoids this by taking a plain object mapping each param name to its own schema, validated independently.

searchParams          // { page: '2', q: 'hello', sort: 'bad' }  (raw strings)
validatedSearchParams // { page: 2, q: 'hello' }                  (parsed, sort dropped)

Only sort gets excluded from validatedSearchParams; page and q come through fine. One broken param not taking down the rest matters more than it sounds once you're dealing with stale bookmarks or hand-edited URLs in a real product.

Client-side only, on purpose

This hook reads window.location.search, so it never runs during server rendering. That's an intentional design choice, not an oversight.

It's safe to render inside an SSR framework (no crash, no hydration mismatch): isSearchParamsReady stays false through the server render and the first client render, then flips to true once the client has read and validated the URL. There's necessarily a brief "not loaded yet" moment before that, though — that part can't be avoided.

If you need validated search params as part of the initial server-rendered output (e.g. a Next.js Server Component, which receives searchParams as a plain prop), skip the hook and validate that object directly with your schema instead. This hook is meant for client-rendered apps (SPAs) or client components that read params after mount.

Handling browser back/forward

v0.2.0 added two ways to react to the URL changing after mount.

For browser back/forward buttons, pass listenToPopstate:

const { validatedSearchParams } = useStandardSearchParams(schema, {
  listenToPopstate: true,
});

It's false by default. That's intentional — the hook's core design is "read the URL once, on mount," and I didn't want to change that behavior silently for existing users. Automatic re-validation is something you opt into, not something that happens by default.

SPA route pushes (router.push(), navigate()) don't fire popstate, so there's a separate refresh() function for that case:

// Next.js
const { validatedSearchParams, refresh } = useStandardSearchParams(schema);
const pathname = usePathname();
const searchParams = useSearchParams();

useEffect(() => {
  refresh();
}, [pathname, searchParams, refresh]);

A small safeguard for development

This hook reads the URL once, on mount. That means an inline schema object (a fresh reference every render) is totally fine — only the keys present on the very first render are ever read. But it also means there's a footgun if the set of schema keys itself needs to change at runtime — for example, validating extra params only for admin users.

To catch this early, there's a dev-only console.warn:

useStandardSearchParams: schema keys changed after mount
(was [page], now [page,q]), but this hook only reads the URL once,
on mount, so the new keys won't be read. If the set of keys genuinely
needs to change at runtime, remount the component (e.g. with a `key`
prop) — memoizing the schema object does not cause a re-parse.

As the message says, the fix is a key prop to force a remount — not useMemo. Memoizing the schema stabilizes its reference, but it does nothing to trigger a re-parse, so the warning spells out the actual fix rather than pointing toward an intuitive-but-wrong one.

Wrapping up

@standard-search-params/react is a small library built around a few ideas:

Standard Schema support, so it works with Zod, Valibot, ArkType, or whatever you're already using
Per-field validation, so one broken param doesn't take the rest down with it
Client-side only, clearly documented rather than papered over
Browser-back and SPA-router support, both opt-in on top of a safe default I'd rather keep the feature set small and the behavior predictable than pile on options.

Feedback and issues are always welcome.

Japanese version (日本語版) is available on Zenn: https://zenn.dev/wdp/articles/72729dd75e506b

Follow-up: Three Design Decisions I Reversed While Building a React Hook

DEV Community: Lei Wang

Three Design Decisions I Reversed While Building a React Hook

Introduction

Background: how the hook behaves

1. "Wrap your schema in useMemo" fixed nothing

Context

My first idea had two holes

Two implementation mistakes too

What I took from it

2. I didn't turn popstate on by default

3. refresh() deduplication created a "silently does nothing" case

Context

The problem

The options

Two smaller fixes in the implementation

Wrapping up

Why I Built @standard-search-params/react Around Standard Schema

Introduction

What is Standard Schema?

Why per-field schemas instead of one big object schema?

Client-side only, on purpose

Handling browser back/forward

A small safeguard for development

Wrapping up

3. `refresh()` deduplication created a "silently does nothing" case