Multi-Framework URL State Manager

Build a URL state management utility that works across different React frameworks using appropriate adapters.

Requirements

Create a utility that manages URL query parameters with support for multiple React framework environments:

1. Framework Adapter Setup: Configure a provider component that wraps your application and sets up the correct adapter for the framework environment (Next.js App Router, React SPA, or test environment).

2. Search State Hook: Implement a search query parameter (q) that:

   • Stores string values in the URL
   • Defaults to an empty string when not present
   • Updates the URL automatically when changed

3. Category Filter Hook: Implement a category filter parameter (category) that:

   • Only accepts: "books", "electronics", or "clothing"
   • Defaults to "books" when not present
   • Updates the URL automatically when changed

Implementation Notes

The solution should use the appropriate adapter for each environment: Next.js App Router adapter for Next.js apps, React adapter for SPAs, and testing adapter for unit tests. The provider component should wrap the application to enable URL state management hooks throughout the component tree.

Test Cases

• When the search query is set to "laptop", the URL should contain ?q=laptop @test
• When the category is changed to "electronics", the URL should contain ?category=electronics @test
• When no query parameters are present, the search should default to empty string and category should default to "books" @test
• In a test environment, URL updates should be trackable and verifiable @test

Implementation

@generates

API

/**
 * Hook to manage search query state in the URL
 * Returns [searchQuery, setSearchQuery] tuple
 */
export function useSearchQuery(): [string, (value: string) => void];

/**
 * Hook to manage category filter state in the URL
 * Returns [category, setCategory] tuple
 */
export function useCategoryFilter(): [string, (value: string) => void];

/**
 * Component that wraps the application with the appropriate framework adapter
 */
export function AppProviders({ children }: { children: React.ReactNode }): React.ReactElement;

Dependencies { .dependencies }

nuqs { .dependency }

Provides URL state management with framework-specific adapters.