← making

eslint-plugin-next-pages-router

An ESLint plugin that catches invalid Pages Router routes before they reach the browser.

2026·Open source tool·live

Created by Project updated Page reviewed

The plugin began with a routing mistake in a real Next.js project.

The bug came from comparing the wrong Pages Router value. The difference between route, pathname, and asPath had stayed invisible until QA surfaced a mismatch in one of the navigation flows.

Instead of adding another convention for the team to remember, I turned the distinction into an ESLint rule.

The first version checked route comparisons and navigation calls against the actual pages/ tree. Version 1.1 extended the same model to next/link, static next.config.mjs files, faster dynamic-route lookup, and more reliable cache invalidation.

Version 1.2.1 added conservative validation for definitely missing dynamic query parameters without reporting runtime-built query objects it cannot prove wrong.

how it works

  • The plugin builds a route model from the project’s `pages/` tree, including static, dynamic, catch-all, and optional catch-all routes.
  • One rule checks comparisons against `route`, `pathname`, and `asPath`; the other checks `router.push`, `router.replace`, and `next/link` navigation targets.
  • Optional Next.js configuration support applies `basePath` and locales, while unresolved runtime values are left alone rather than guessed.

project facts

  • The published package is version 1.2.1 and supports ESLint 8–9, Node.js 16+, and Next.js 10+ projects using the Pages Router.
  • The verified 1.2.0–1.2.1 benchmark found overlapping timing ranges rather than a measurable speedup or regression; its fixture workload produced 150 additional missing-parameter diagnostics in 1.2.1.

official sources

  • eslint
  • next.js
  • routing