Nuqs Scaffolder

// __name__-filters.test.tsx — Vitest tests for <__NAME__Filters />.
// Generated by nuqs-scaffolder. Asserts that the URL drives state and vice versa.

import { describe, it, expect } from 'vitest';
import { render, screen, fireEvent } from '@testing-library/react';
import { NuqsTestingAdapter } from 'nuqs/adapters/testing';

import { __NAME__Filters } from './__name__-filters';

function renderWithSearch(searchParams: Record<string, string> = {}) {
  return render(
    <NuqsTestingAdapter searchParams={searchParams}>
      <__NAME__Filters />
    </NuqsTestingAdapter>
  );
}

describe('<__NAME__Filters />', () => {
  it('renders without crashing under NuqsTestingAdapter', () => {
    renderWithSearch();
    // Smoke test — the form must mount even with no initial params.
    expect(screen.getByRole('form')).toBeInTheDocument();
  });

  /*= TEST_CASES =*/
  // For each entry in spec.params, emit ONE `it(...)` block that verifies the
  // initial URL value flows into the rendered field. Recipes:
  //
  // string:
  //   it('reads __key__ from the URL', () => {
  //     renderWithSearch({ __key__: 'hello' });
  //     expect(screen.getByLabelText('__key__')).toHaveValue('hello');
  //   });
  //
  // integer / float:
  //   it('reads __key__ as a number from the URL', () => {
  //     renderWithSearch({ __key__: '42' });
  //     expect(screen.getByLabelText('__key__')).toHaveValue(42);
  //   });
  //
  // boolean:
  //   it('reads __key__ as a checkbox state from the URL', () => {
  //     renderWithSearch({ __key__: 'true' });
  //     expect(screen.getByLabelText('__key__')).toBeChecked();
  //   });
  //
  // string-literal:
  //   it('reads __key__ as the selected option from the URL', () => {
  //     renderWithSearch({ __key__: <one of spec.values> });
  //     expect(screen.getByLabelText('__key__')).toHaveValue(<that value>);
  //   });
  //
  // array-of-string-native:
  //   it('renders chips for each __key__ value in the URL', () => {
  //     renderWithSearch({ __key__: 'a', __key__: 'b' }); // NuqsTestingAdapter accepts query strings; use those for multi-value keys.
  //     // ...
  //   });
  //
  // Skip json types — assertions are shape-specific; write those by hand.

  it('Reset clears every filter back to the default', () => {
    renderWithSearch({ /* fill in non-default values for each param */ });
    fireEvent.click(screen.getByRole('button', { name: /reset/i }));
    // After clicking Reset, every input should show its default value.
  });
});

// __name__-filters.tsx — client component for the __NAME__ page.
// Generated by nuqs-scaffolder. Uses the shared parser map from __module__-search-params.ts.

'use client';

import { useQueryStates } from 'nuqs';

import { __name__SearchParams } from '@/__libDir__/__module__-search-params';

/**
 * URL-backed filters for the /__module__ page. Edit the spec, not this file —
 * field rendering below is generated to match spec.params.
 */
export function __NAME__Filters() {
  const [filters, setFilters] = useQueryStates(__name__SearchParams);

  return (
    <form className="filters" onSubmit={(e) => e.preventDefault()}>
      /*= COMPONENT_FIELDS =*/
      // For each entry in spec.params, emit ONE field block. Use these recipes:
      //
      // string:
      //   <label>
      //     __key__
      //     <input
      //       type="text"
      //       value={filters.__key__}
      //       onChange={(e) => setFilters({ __key__: e.target.value })}
      //     />
      //   </label>
      //
      // integer / float / index / hex:
      //   <label>
      //     __key__
      //     <input
      //       type="number"
      //       value={filters.__key__ ?? ''}
      //       onChange={(e) => setFilters({ __key__: e.target.value === '' ? null : Number(e.target.value) })}
      //     />
      //   </label>
      //
      // boolean:
      //   <label>
      //     <input
      //       type="checkbox"
      //       checked={filters.__key__}
      //       onChange={(e) => setFilters({ __key__: e.target.checked })}
      //     />
      //     __key__
      //   </label>
      //
      // iso-date / iso-date-time:
      //   <label>
      //     __key__
      //     <input
      //       type={spec.type === 'iso-date' ? 'date' : 'datetime-local'}
      //       value={filters.__key__?.toISOString().slice(0, 10) ?? ''}
      //       onChange={(e) => setFilters({ __key__: e.target.value === '' ? null : new Date(e.target.value) })}
      //     />
      //   </label>
      //
      // string-literal (renders a <select>):
      //   <label>
      //     __key__
      //     <select
      //       value={filters.__key__}
      //       onChange={(e) => setFilters({ __key__: e.target.value as (typeof __name__SearchParams.__key__.values)[number] })}
      //     >
      //       {/* one <option> per spec.params.__key__.values */}
      //     </select>
      //   </label>
      //
      // array-of-string / array-of-string-native (multi-select chips):
      //   <fieldset>
      //     <legend>__key__</legend>
      //     {filters.__key__.map((tag) => (
      //       <button
      //         key={tag}
      //         type="button"
      //         onClick={() =>
      //           setFilters({ __key__: filters.__key__.filter((t) => t !== tag) })
      //         }
      //       >
      //         {tag} ×
      //       </button>
      //     ))}
      //     {/* an input that pushes onto filters.__key__ when the user submits */}
      //   </fieldset>
      //
      // json:
      //   {/* shape-specific UI — write by hand */}

      <button
        type="button"
        onClick={() => setFilters(null)}  // Clears every key back to its default
      >
        Reset
      </button>
    </form>
  );
}

// __module__-search-params.server.ts — server-side bindings for the __NAME__ page.
// Generated by nuqs-scaffolder. Imports nuqs/server (not nuqs) so the 'use client'
// boundary doesn't get contaminated.
//
// Three exports:
//   loadSearchParams        — call this in your page() at the top
//   __module__SearchParamsCache — use this for nested Server Components that need .get()
//   serialize__NAME__       — build canonical URLs (links, redirects, generateMetadata)
//
// The schema export at the bottom plugs straight into tRPC, TanStack Router, or any
// other Standard Schema consumer.

import {
  createLoader,
  createSearchParamsCache,
  createSerializer,
  createStandardSchemaV1,
} from 'nuqs/server';

// Re-import the parser map from the shared file. DO NOT redefine — drift kills SSR.
import { __name__SearchParams } from './__module__-search-params';

/**
 * Use in your page when you don't need nested Server Components to read params:
 *
 *   export default async function Page({ searchParams }) {
 *     const params = await loadSearchParams(searchParams);
 *     return <Results {...params} />;
 *   }
 */
export const loadSearchParams = createLoader(__name__SearchParams);

/**
 * Use when nested Server Components need to .get() params without prop drilling:
 *
 *   export default async function Page({ searchParams }) {
 *     await __module__SearchParamsCache.parse(searchParams);
 *     return <NestedTree />;  // children call __module__SearchParamsCache.get('q')
 *   }
 */
export const __module__SearchParamsCache = createSearchParamsCache(__name__SearchParams);

/**
 * Build a canonical URL for the /__module__ page. Use in generateMetadata for SEO
 * and anywhere you need an SSR-safe link.
 *
 *   const url = serialize__NAME__('/__module__', { q: 'react' });
 */
export const serialize__NAME__ = createSerializer(__name__SearchParams, {
  // Stable key order across renders prevents SEO duplicate-URL bugs.
  processUrlSearchParams(params) {
    params.sort();
    return params;
  },
});

/**
 * Standard Schema export — plug into tRPC, TanStack Router, or any Standard Schema
 * consumer that needs to validate the same shape.
 */
export const __name__SearchParamsSchema = createStandardSchemaV1(__name__SearchParams);

// __module__-search-params.ts — shared parser map for the __NAME__ page.
// Generated by nuqs-scaffolder. Edit the spec, don't hand-edit this file —
// drift between this file and __module__-search-params.server.ts breaks SSR/CSR consistency.
//
// Imported from BOTH client (useQueryStates) and server (createSearchParamsCache).
// Safe to import from either side: `nuqs` is client-marked at runtime but the parser
// builders are tree-shakeable pure values.

import {
  /*= PARSER_IMPORTS =*/
  // Pick the imports from this set based on which `type`s appear in spec.params:
  //   parseAsString, parseAsInteger, parseAsFloat, parseAsBoolean,
  //   parseAsIsoDate, parseAsIsoDateTime, parseAsTimestamp,
  //   parseAsHex, parseAsIndex,
  //   parseAsArrayOf, parseAsNativeArrayOf,
  //   parseAsStringLiteral, parseAsNumberLiteral,
  //   parseAsJson
} from 'nuqs';

/*= ZOD_SCHEMAS =*/
// For each spec.params[key] with type === 'json', emit:
//   import { z } from 'zod';
//   export const __NAME____key__Schema = z.object({ /* TODO: fill in fields */ });
// Skip this entire block if no params are json-typed.

/**
 * Parser map for /__module__ URL state.
 *
 * Consume on the client with:
 *   const [state, setState] = useQueryStates(__name__SearchParams);
 *
 * Consume on the server with:
 *   await loadSearchParams(searchParams)   // see __module__-search-params.server.ts
 */
export const __name__SearchParams = {
  /*= PARSERS =*/
  // For each entry in spec.params, emit ONE line of the form:
  //   <key>: <parser-chain>,
  //
  // Construct <parser-chain> per the `type`:
  //   string                    → parseAsString
  //   integer                   → parseAsInteger
  //   float                     → parseAsFloat
  //   boolean                   → parseAsBoolean
  //   iso-date                  → parseAsIsoDate
  //   iso-date-time             → parseAsIsoDateTime
  //   timestamp                 → parseAsTimestamp
  //   hex                       → parseAsHex
  //   index                     → parseAsIndex
  //   array-of-string           → parseAsArrayOf(parseAsString)
  //   array-of-string-native    → parseAsNativeArrayOf(parseAsString)
  //   string-literal            → parseAsStringLiteral([...spec.values] as const)
  //   number-literal            → parseAsNumberLiteral([...spec.values] as const)
  //   json                      → parseAsJson(<ZodSchema>.parse)
  //
  // Append `.withDefault(<value>)` ONLY if spec.default is not null.
  // For `array-of-*`, render the default as an array literal.
  // For `string-literal`, the default must be one of `values`.
} as const;

export type __NAME__SearchParams = {
  // Optional: emit a type alias if helpful. Most callers can rely on inferQueryStates<typeof __name__SearchParams>.
};

{
  "$comment": "nuqs-scaffolder spec — fill in name, module, and params, then ask the skill to render the four files.",

  "name":   "__NAME__",
  "module": "__module__",

  "params": {
    "q":          { "type": "string",                                    "default": "" },
    "page":       { "type": "integer",                                   "default": 1 },
    "categories": { "type": "array-of-string-native",                    "default": [] },
    "sort":       { "type": "string-literal", "values": ["asc","desc"],  "default": "asc" }
  }
}

{
  "lib_dir": "lib",
  "components_dir": "components",
  "generate_tests": true,
  "test_runner": "vitest",
  "file_case": "kebab",
  "adapter_import": "nuqs/adapters/next/app",
  "_setup_instructions": {
    "lib_dir": "Directory (relative to repo root) where parser maps go. Default 'lib' fits Next.js App Router.",
    "components_dir": "Directory for client filter components. Default 'components'.",
    "generate_tests": "Whether to emit a .test.tsx file alongside each component. Set false if the project has no test runner.",
    "test_runner": "One of: vitest, jest. Determines test-template syntax and imports.",
    "file_case": "Filename case style. 'kebab' = search-filters.tsx (recommended). 'pascal' = SearchFilters.tsx.",
    "adapter_import": "Which NuqsAdapter the test wraps. Use 'nuqs/adapters/testing' inside tests; this setting is for the server-side imports."
  }
}

{
  "version": "1.0.4",
  "organization": "Community",
  "technology": "nuqs",
  "discipline": "extraction",
  "type": "scaffolding",
  "date": "May 2026",
  "abstract": "Template-driven scaffolder for nuqs URL-state filters in Next.js App Router. From a single JSON spec, generates four coherent files — client parser map, server loader/cache/serializer, client component, and Vitest test — all sharing one parser definition map per the nuqs Standard Schema pattern. Encodes the v2.5+ conventions from the companion `nuqs` distillation skill.",
  "references": [
    "https://nuqs.dev/docs/parsers/built-in",
    "https://nuqs.dev/docs/server-side",
    "https://nuqs.dev/docs/testing",
    "https://nuqs.dev/blog/nuqs-2.5"
  ]
}