@paramour-js/next

@paramour-js/next is the Next.js integration for paramour: the build-time registry wrapper, client hooks for both routers, and the paramour CLI. The package ships five module entry points plus a binary — import from the entry that matches where the code runs.

. — build-time integration

The main entry exports the Next config wrapper and its supporting types: withTypedRoutes generates and validates the paramour-env.d.ts registry artifact during next dev and next build, with WithTypedRoutesOptions (outFile, strict) controlling where the artifact lives and whether drift fails the build. It also exports ParamourConfig, the type of the paramour.config.ts file the CLI reads, and RouteCollisionError, thrown when two files resolve to one URL. These four are the entry's entire public surface.

./app — App Router hooks

Client hooks for App Router components: useRouteParams, useSearch, and their OrThrow variants, all taking the same route objects you define with defineAppRoute. App-Router params are synchronously available on the client, so results are two-arm SafeResult unions with no loading state. Every hook accepts an optional SelectOptions projection. The module carries "use client" — these are client-component hooks.

./pages — Pages Router hooks

Client hooks for Pages Router components: useRouteParams and useSearch for routes defined with definePagesRoute. They return a three-state RouterResult — SafeResult plus a pending arm for the pre-hydration render of statically-optimized pages — and there are deliberately no OrThrow variants. The same SelectOptions bag applies.

./testing — testing provider

A provider for unit-testing client components that call the hooks: ParamourTestingProvider and withParamourTesting, the latter a wrapper factory for testing-library's wrapper option. One provider feeds both router flavors, and it overrides the hooks' framework reads through context — no next/* module mocking, any test runner. The entry depends only on React and is client-only, like the hook modules.

./devtools-seam — devtools contract (types only)

A types-only entry: the contract between the observation seam inside the hooks and the @paramour-js/devtools-panel panel that consumes it. You import from it only when building tooling on top of the seam — application code never needs it. The panel itself is documented in the @paramour-js/devtools-panel reference.

The paramour binary

Installing the package puts a paramour CLI on your path with six commands — generate, check, init, list, doctor, and skills — covering artifact generation, CI drift verification, project setup, route inspection, setup diagnosis, and agent-skill installation. One exit-code contract holds across all of them.