The Complete Production SOP: Enforcing nuqs Type-Safe URL Search Parameters for Next.js in Autonomous AI Agents

---
name: "nuqs-type-safe-search-params"
description: "Synchronize React state with URL query parameters with strict parser types and shallow routing."
---
# Execution SOP & Rules
1. Install nuqs dependency.
2. Wrap root layout with `<NuqsAdapter>`.
3. Implement typed search state using `useQueryState` and explicit parsers.
4. Apply `{ shallow: true }` and debounced transitions.

import { NuqsAdapter } from 'nuqs/adapters/next/app';
import './globals.css';

export default function RootLayout({
  children,
}: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  );
}

'use client';

import { useQueryState, parseAsString, parseAsInteger } from 'nuqs';
import { useTransition } from 'react';

export function ProductFilters() {
  const [isLoading, startTransition] = useTransition();

  const [search, setSearch] = useQueryState(
    'q',
    parseAsString.withDefault('').withOptions({
      shallow: true,
      history: 'replace',
      throttleMs: 300,
    })
  );

  const [page, setPage] = useQueryState(
    'page',
    parseAsInteger.withDefault(1).withOptions({
      shallow: true,
    })
  );

  return (
    <div className="flex flex-col gap-4 p-4 border rounded-md">
      <input
        type="text"
        value={search}
        placeholder="Search products..."
        onChange={(e) => setSearch(e.target.value || null)}
        className="border px-3 py-2 rounded text-sm"
      />
      <div className="flex items-center gap-2">
        <button
          disabled={page <= 1}
          onClick={() => setPage((p) => Math.max(1, p - 1))}
          className="px-3 py-1 bg-gray-200 rounded disabled:opacity-50"
        >
          Previous
        </button>
        <span className="text-sm">Page {page}</span>
        <button
          onClick={() => setPage((p) => p + 1)}
          className="px-3 py-1 bg-gray-200 rounded"
        >
          Next
        </button>
      </div>
    </div>
  );
}

#!/usr/bin/env bash
set -euo pipefail
echo "Validating TypeScript and Next.js build..."
pnpm tsc --noEmit
pnpm next lint
echo "Verification successful!"