Skip to content

Latest commit

 

History

History
99 lines (69 loc) · 3.8 KB

AGENTS.md

File metadata and controls

99 lines (69 loc) · 3.8 KB

AGENTS GUIDE

Operational instructions for autonomous coding / AI agents contributing to the nuqs repository.

nuqs is a library for type-safe URL query string ↔ React state synchronization with minimal bundle size and zero dependencies.

Refer to: README.md & CONTRIBUTING.md for authoritative detail.

Essential Context

Repository Structure (Monorepo)

  • Library source: packages/nuqs
  • Documentation app (Next.js + Fumadocs): packages/docs
    • MDX content: packages/docs/content
  • End-to-end test benches: packages/e2e
    • Framework targets: Next.js app/pages, React SPA, Remix, TanStack Router, React Router v6/v7
  • Examples: packages/examples/*

Core Concepts (nuqs)

  • Goal: Type-safe URL query string ↔ React state sync.
  • Main Hooks:
    • useQueryState(key, parserOrConfig)
    • useQueryStates(configObject, options)
  • Parsers: Provide parse & serialize; enhanced with .withDefault() & .withOptions()
  • Batching & Throttling: Multiple state updates in one tick are merged; URL updates throttled (≥50ms)
  • Key Principles:
    1. URL = single source of truth
    2. Serialization must be lossless & pure
    3. Defaults are internal (not written to URL)
    4. Invalid parse → return null

Configuration

  • Package manager: pnpm
  • Build: pnpm build
  • Test suite: pnpm test (5-10 minutes; includes build + unit + typing + e2e)
  • Development: pnpm dev --filter <package-name>... (triple dots start dependencies' dev script too)

Development Guidelines

For detailed development guidelines organized by task, see:

Quick Reference: Common Tasks

Task Guide
Fix a bug See Testing Patterns → Regression
Add a new parser See Parser Implementation
Add a framework adapter See Adapter Development
Improve performance See API Design → Performance & Reliability
Update documentation See Release & Git Workflow → Documentation
Prepare a pull request See Release & Git Workflow → PR Quality Checklist

Debugging

Enable debug logs in the browser console:

localStorage.setItem('debug', 'nuqs')

In server or Node environments (e.g. when using nuqs/server), set the DEBUG environment variable so it contains nuqs:

DEBUG=nuqs pnpm dev

Log lines are prefixed with [nuq+]

Encourage debug logs in issue reports and include them in reproduction scripts.

Exit Conditions for Agent Tasks

A task is DONE when:

  • All checklist items satisfied
  • Tests pass locally (pnpm test)
  • Docs consistent with behavior
  • No unresolved TODOs introduced
  • No stray console logs (except controlled debug support)