home / skills / andrelandgraf / fullstackrecipes / url-state-management

url-state-management skill

safe

/skills/url-state-management

This skill helps you sync React state to URL query parameters for shareable filters, search, and deep links using nuqs.

npx playbooks add skill andrelandgraf/fullstackrecipes --skill url-state-management

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.2 KB

---
name: url-state-management
description: Sync React state to URL query parameters for shareable filters, search, and deep-linkable dialogs with nuqs.
---

# URL State Management

Sync React state to URL query parameters for shareable filters, search, and deep-linkable dialogs with nuqs.

## Prerequisites

Complete these recipes first (in order):

### Next.js on Vercel

Create a Next.js app running on Bun, configure the development environment, and deploy to Vercel with automatic deployments on push.

```bash
curl -H "Accept: text/markdown" https://fullstackrecipes.com/api/recipes/nextjs-on-vercel
```

## Cookbook - Complete These Recipes in Order

### URL State with nuqs

Sync React state to URL query parameters for shareable filters, search queries, and deep links to modal dialogs. Preserves UI state on browser back/forward navigation.

```bash
curl -H "Accept: text/markdown" https://fullstackrecipes.com/api/recipes/nuqs-setup
```

### Working with nuqs

Manage React state in URL query parameters with nuqs. Covers Suspense boundaries, parsers, clearing state, and deep-linkable dialogs.

```bash
curl -H "Accept: text/markdown" https://fullstackrecipes.com/api/recipes/using-nuqs
```

Overview

This skill syncs React state to URL query parameters using nuqs to enable shareable filters, preserved search queries, and deep-linkable dialogs. It provides production-ready patterns and step-by-step guidance for integrating URL-driven UI state into full stack web AI apps. Ideal for apps that need back/forward navigation fidelity and easy sharing of UI state via links.

How this skill works

The skill shows how to map React state to query parameters with nuqs, including parsing, serialization, and default value handling. It covers preserving UI state across navigation, clearing and resetting query-driven state, and making modal dialogs deep-linkable so they open from a URL. Recipes include setup, Suspense-aware usage, and practical patterns for Next.js deployments.

When to use it

When you need shareable links that reproduce UI filters and search queries
To preserve component state across browser back and forward navigation
When building deep links to open modal dialogs or specific app views
For server-rendered apps (Next.js) that require consistent URL-driven state
When you want predictable parsing and validation of URL query values

Best practices

Define clear parsers and serializers for each query param to avoid type drift
Keep URL state minimal—store only values needed to reconstruct the UI
Use sensible defaults and fallback logic so missing params degrade gracefully
Coordinate nuqs state with Suspense boundaries for async data fetching
Provide explicit clear/reset controls to remove sensitive or stale query data

Example use cases

A product listing with sortable, filterable, and paginated results shareable via URL
A search page where queries and selected facets persist across navigation
Opening a settings or info modal directly from a bookmarked URL
Prepopulating form inputs from query params for invite or referral flows
Deep-linking to a specific AI model configuration or conversation state

FAQ

Do I need Next.js to use this pattern?

No—nuqs works in client React apps, but the recipes include Next.js deployment guidance to ensure server rendering and routing integrate smoothly.

How do I avoid exposing sensitive data in the URL?

Keep sensitive values out of query params; store them server-side or in session storage. Use query params only for non-sensitive UI state.