nuqs-setup_skill

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.