state-in-url: Instructions file for Codex

AGENTS — state-in-url

Guidance for AI coding agents working on this repository. If you are here to use the library in someone else's project, read skills/ instead — those files are written for that, and are far more specific than this one. npx @tanstack/intent@latest install wires them into your agent.

What this is

state-in-url is a ~2KB, zero-runtime-dependency React library that stores typed, JSON-serializable state objects in URL query parameters while preserving types and structure (numbers stay numbers, dates stay dates, nested objects/arrays work). It ships a useUrlState hook per framework, each behind its own entry point: state-in-url/next (App Router), /react-router (v7), /react-router6, /remix, /astro (React islands), and /react for a plain React app with no router at all. useUrlStateBase builds one for a router with no entry point of its own. Plus framework-agnostic encode/decode helpers. Positioned as a NUQS alternative.

Commands

This is a pnpm monorepo. pnpm is enforced (only-allow). Most scripts run through wireit (caching/dependency graph), so always invoke them via pnpm run <script>, not the underlying tool directly.

• pnpm run test — full suite: tsc typecheck → unit tests → build all packages → exports test → integration (e2e) tests. Everything CI checks, but not the command CI runs — .github/workflows/tests.yml splits it into three parallel jobs and calls the tools directly, so a break in this wiring shows up locally only.
• pnpm run test:unit — Vitest unit tests (depends on tsc), single run, ~2s; coverage is on in the config. Use npx vitest directly for watch mode.
• pnpm run test:int — Playwright e2e (--project=chromium). Kills any leftover demo servers, starts all eight, and waits for all eight before the first test. To run against a set you started yourself (pnpm run start), call pnpm exec playwright test directly — a partial leftover set is reused as-is by Playwright and never completed, which is the failure the kill avoids.
• pnpm run tsc — tsc --noEmit typecheck only.
• pnpm run test:consumers — packs the tarball, installs it into throwaway projects under every available package manager (pnpm, npm, yarn node-modules, yarn PnP, bun; missing ones are skipped and named), and checks every subpath resolves in ESM and in CJS against each supported framework, plus Vitest and Jest runs and a real Next App Router build. Install-bound (~1-2 min), so it is a pre-release gate rather than part of the unit loop. A tarball, not the workspace: workspace:* symlinks the package outside node_modules, which changes both pnpm's peer resolution and Vitest's externalization.
• pnpm run build — Rollup build of the library into dist/ (ESM .mjs + .d.ts, plus a .cjs build that the exports map deliberately does not point at — see Packaging).
• pnpm run dev — library in Rollup watch mode + all example apps, each at http://<package-name>.localhost:1355 (see Demo app URLs).
• pnpm run kill — kill hung Next/Vite/wireit processes (use this if dev/test servers hang).
• pnpm run cleanup / pnpm run reinstall — nuke build artifacts and node_modules.
• pnpm run setup — playwright install --with-deps (needed before e2e on a fresh machine).
• pnpm run test:lighthouse — Lighthouse audits of the demo site (see below). Builds and serves it itself; nothing needs to be running first.
• pnpm i18n status / pnpm i18n:check — the eight translations: drift from the English source, and README structure/links/anchors. pnpm i18n:toc rebuilds the tables of contents; pnpm i18n:copy:check covers the demo's copy modules.