home / skills / andrelandgraf / fullstackrecipes / nuqs-setup

nuqs-setup skill

safe

This skill syncs React state with URL query parameters to enable shareable filters and deep links while preserving UI state.

npx playbooks add skill andrelandgraf/fullstackrecipes --skill nuqs-setup

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

Files (1)

SKILL.md

533 B

---
name: nuqs-setup
description: 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.
---

# URL State with nuqs

To set up URL State with nuqs, refer to the fullstackrecipes MCP server resource:

**Resource URI:** `recipe://fullstackrecipes.com/nuqs-setup`

If the MCP server is not configured, fetch the recipe directly:

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

Overview

This skill syncs React state to URL query parameters to create shareable filters, search queries, and deep links to modal dialogs. It preserves UI state across browser back/forward navigation and is implemented in TypeScript for production-ready full stack web AI apps. The setup follows a compact recipe that works with a Shadcn-based UI and integrates easily into existing React routing.

How this skill works

The setup serializes selected pieces of component state into URL query parameters and restores them on mount or navigation events. It listens for popstate events so back/forward navigation restores previous UI state instead of only changing the route. The recipe exposes simple helpers to read, write, and debounce query updates so you can keep the URL authoritative without frequent re-renders.

When to use it

You need shareable links that preserve current filters, search text, or sort order.
You want deep links to open specific modal dialogs or views with preserved state.
You need consistent behavior when users navigate with browser back/forward buttons.
You want bookmarkable application states for debugging or user support.
You are building a Shadcn-styled React app with TypeScript and predictable routing.

Best practices

Serialize only the minimal, stable state needed for reproduction (avoid full component trees).
Keep query parameter keys short and consistent to reduce URL length and improve readability.
Debounce frequent updates like typing to avoid excessive history entries.
Provide sensible defaults when reading params so the UI remains robust against invalid URLs.
Document query keys in one place to keep components aligned and avoid conflicts.

Example use cases

A product listing with filter chips and a search box that can be shared with the current filters applied.
A dashboard where users can link directly to a modal showing item details or an editor with preset fields.
An analytics page where date range, metrics, and grouping are encoded in the URL for reproducible reports.
A multi-step form where progress and selected options persist when users navigate back and forth.

FAQ

Do I need a special server to use this?

No. The recipe can be fetched from the MCP server URL, but it works client-side in any React app. If the MCP endpoint is unavailable, you can retrieve the recipe directly via the provided curl command.

How does this handle large or sensitive state?

Avoid placing sensitive data in the URL. For large state, store an identifier in the query and keep the full payload on the server or local storage, fetching it when the ID is present.