Imported from ya2s/next-typed-url (AGENTS.md). Install upstream with npx skills add ya2s/next-typed-url. Copyright stays with the author.

Agent Guide for next-typed-url

This package is a CLI/library that scans Next.js Pages Router and App Router apps and generates typed URL builders (buildUrl, {app}Url, urls). Follow the policies below to avoid breaking existing consumers.

Before You Start

• Read README.md and the implementation under src/ to understand the output directory layout and CLI flags (--root, --apps, --app-name, --out, --exclude-404).
• Keep type definitions self-contained in src/; avoid introducing heavy external dependencies.
• If you change CLI input/output behavior or logging, review the downstream scripts in the monorepo that might rely on it.

Implementation Guidelines

• Minimize diffs and align with the existing naming/function structure (most logic lives in generator.ts). Remember: each app outputs builder.ts (raw buildUrl) and index.ts (wrapping helpers), and the root index.ts exposes both {app}Url and the urls dictionary.
• When adding new CLI flags, update both option parsing and the programmatic API, then document the changes in the README and this guide.
• Changes to route detection must keep the current exclusions (Pages Router api/, _app, _document, _error, 500, etc.) and also respect App Router semantics: only page.{ts,tsx,js,jsx} / default.* files produce routes, while route groups (group) and parallel segments (@modal, intercepting segments) are ignored when constructing the URL path. Cover dynamic segments ([id], [...slug], [[...slug]]) with automated tests.
• To add typed search parameters, define export type Query = { ... } (or export interface Query) inside the page module. The generator imports that type and wires it to the route’s searchParams (stay consistent with Next.js's params/searchParams nomenclature).
• Respect the public output structure: each app directory emits builder.ts (raw buildUrl) and index.ts (e.g., webUrl.build/href/pathname). The root index.ts must re-export {app}Url and the urls dictionary.

Testing & Build

• Unit tests are currently minimal. When you touch the core logic, consider adding Vitest suites under src/ and reuse the sample apps/out directories as fixtures.
• Build artifacts in dist/ must not be committed. Use npm run build (or pnpm run build) to verify TypeScript output when necessary.
• Always run Biome (pnpm format, pnpm lint) before committing. Include formatting changes in the same commit.
• For query-type changes, ensure the relevant pages export Query and that generated output reflects the expected types; cover this with unit tests if possible.

Documentation Updates

• Update README.md whenever you change the public API or CLI arguments.
• If you add new rules for contributors, append them here and mention the update in your commit message.

Release & Publishing

• This package targets npm distribution. When bumping the version, use npm version (or equivalent) to keep semver and tags in sync, then verify generated artifacts before publishing.
• For CI changes (e.g., GitHub Actions), follow the repository-wide conventions defined in AGENTS.md or related docs.