johnidm / johnidm/antenna

Implement URL state params using nuqs

Open
#45 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
2
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Here is the template for implementing URL state params using `nuqs`.

*A quick candid note before you copy this over:* Since you are using TanStack Router, keep in mind that it already has a highly robust, built-in, and type-safe search parameters API (`validateSearch` and `useSearch`). However, `nuqs` is an excellent, specialized library with great DX for this exact pattern. The template below is tailored for `nuqs` as requested, but I've added a note at the bottom to ensure the team is aligned on why `nuqs` is being used over the router's native capabilities.

***

### **Title:** [Feature] - Implement URL state params using nuqs

### **Description**
Currently, elements of our UI state (such as search queries, filters, or pagination) are likely trapped in local React state (`useState`). To improve the user experience, make pages bookmarkable, and allow users to share exact views via links, we need to lift this state into the URL search parameters. We will be using [`[nuqs](https://www.google.com/search?q=%5Bhttps://nuqs.dev/%5D(https://nuqs.dev/))`]([https://nuqs.dev/](https://nuqs.dev/)) to achieve this in a type-safe and developer-friendly way.

### **Goals**
* Synchronize local component state with the URL query string (e.g., `?q=searchterm&page=2`).
* Ensure that direct navigations to URLs with existing search parameters automatically hydrate the UI state.
* Maintain strict type safety for our URL parameters.

### **Acceptance Criteria**
- [ ] **Setup:** Install `nuqs` and configure the necessary framework adapter for our routing setup at the root level.
- [ ] **Implementation:** Identify at least one stateful component (e.g., a search bar, data table pagination, or filter sidebar) and migrate its local state to `nuqs` (`useQueryState` or `useQueryStates`).
- [ ] **Validation:** Verify that updating the UI updates the URL immediately (or debounced, depending on the UX need).
- [ ] **Validation:** Verify that refreshing the page or pasting the URL in a new tab preserves the exact state of the UI.
- [ ] **History:** Ensure browser back/forward buttons work naturally with the parameter updates (configure `history: 'push'` or `'replace'` as appropriate).

### **Technical Implementation Details**
To integrate `nuqs` outside of Next.js, we need to wrap our application tree in the appropriate adapter so it can hook into our router's history.

**1. Basic Usage Example:**
Replacing a standard `useState` with `useQueryState`:
```tsx
import { useQueryState } from 'nuqs'

export function SearchFilter() {
// 'q' becomes the URL parameter key: ?q=...
const [search, setSearch] = useQueryState('q')

return (
setSearch(e.target.value)}
placeholder="Search..."
/>
)
}
```

**2. Parsing and Type Safety:**
Use parsers for non-string values (like integers for pagination):
```tsx
import { useQueryState, parseAsInteger } from 'nuqs'

const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
```

### **Additional Notes**
* **Architecture Alignment:** TanStack Router natively supports strongly-typed search parameters. The decision to use `nuqs` here is to leverage its specific DX and API surface (like drop-in `useState` replacements and built-in parsers). We should ensure we aren't creating competing sources of truth between `nuqs` and TanStack Router's `Route.useSearch()`.
* Check the [[nuqs Adapters Documentation](https://nuqs.dev/docs/adapters)](https://nuqs.dev/docs/adapters) to ensure we wrap our app provider correctly for our current framework/router.

***

**Labels:** `feature`, `state-management`, `ux`

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.