{"slug": "find-missing-loading-and-error-states-in-next-js-with-unhappypath", "title": "Find Missing Loading and Error States in Next.js with unhappypath", "summary": "An open-source CLI called unhappypath, at version 0.1.0 in package.json and built from commit 0827ee0, scans Next.js and React source code for missing loading, error, empty and pending UI states without running a browser or calling an LLM, producing a 0-100 score plus findings tied to file, line and rule ID. The MIT-licensed tool requires Node.js 20 or newer and reports 38/100 with 14 findings on its deliberately broken demo fixture versus 100/100 with zero findings on its complete fixture, with rule IDs such as RTE-01 for a missing loading boundary and QRY-02 for a query without visible error handling. The CLI supports --json, --markdown and --min-score flags, exiting 0 on success, 1 when the threshold is not met and 2 on a usage error, and its 18 tests passed in the current checkout.", "body_md": "# Find Missing Loading and Error States in Next.js with unhappypath\n\nAI coding tools are good at making the successful path visible quickly. They can produce a page that loads data, accepts a form, and responds to a button click while leaving the slower, empty, failed, or repeated paths unfinished. That gap is easy to miss in a screenshot. It is also expensive to fin\n\nd manually across every route and component. unhappypath is a small open-source CLI that scans source code for several of these missing UI states. It does not run a browser or call an LLM. It produces a repeatable score and findings that point to files, lines, and rule IDs.\n\nThis tutorial uses the current main source at commit 0827ee0. The repository currently reports version 0.1.0 in package.json, requires Node.js 20 or newer, and is licensed under MIT. There is no public release or tag, so the commands below describe the current repository state rather than a stable release. Clone the repository, install its dependencies, build it, and scan a project directory: git clone https://github.com/paladini/unhappypath.git cd unhappypath npm ci npm run build node dist/cli.js /path/to/your-next-app The result includes a score from 0 to 100, four dimension scores, and findings such as RTE-01 for a missing loading boundary or QRY-02 for a query without visible error handling.\n\nYou need Git, Node.js 20 or newer, npm, and a local Next.js or React project to inspect. The scanner reads source files from disk. It does not need a running development server, a database, API credentials, or network access after dependencies are installed. The project depends on TypeScript for its build and uses Node's built-in test runner.\n\nIts package metadata declares MIT licensing and the CLI entry point as dist/cli.js. The repository documents npm ci followed by npm run build. Run those commands from the repository root: npm ci npm run build After the build, the executable is available at dist/cli.js. The package also exposes an unhappypath binary when installed as a package, but building from source makes the inspected commit explicit.\n\nRun the project's tests before using it in a workflow: npm test In the current checkout, this completed successfully with 18 tests. The test command builds first and then executes the compiled tests, so a successful result covers both the TypeScript compilation and the repository's fixture contracts. Point the CLI at the directory that contains the application source: node dist/cli.js /path/to/your-next-app The path is positional. If you omit it, the CLI uses the current directory.\n\nFor a machine-readable report, add --json; for a Markdown report, use --markdown. To make the command fail when the score is below a threshold, use --min-score: node dist/cli.js . --json --out unhappypath-report.json --min-score 75 The CLI documents exit code 0 for a successful scan, 1 when --min-score is not met, and 2 for a usage error. A threshold is a policy choice, not a claim that the application is production-ready.\n\nThe scanner only checks the signals implemented by its rules. The repository includes a deliberately incomplete project and a project with the expected boundaries. Run both demos: npm run demo:broken npm run demo:good The broken fixture currently reports 38/100 and 14 findings. It includes missing route boundaries, a query without loading, error, or empty handling, a form without pending feedback, a fetch effect without loading and error state, and an asynchronous click without a disabled or pending state.\n\nThe good fixture reports 100/100 and zero findings. That is useful for checking the command and output format, but it is not evidence that an arbitrary application has complete UX coverage. The fixture is intentionally shaped around the scanner's current heuristics. The rule IDs are stable within the repository's documented ups-v1 reference.\n\nRoute checks include: RTE-01: a route page has no loading boundary in its segment or ancestors. RTE-02: a route has no not-found.tsx boundary in its segment or ancestors. RTE-03: a route has no error.tsx boundary in its segment or ancestors. RTE-04: the application has no root global-error.tsx.\n\nFor data and interaction code, query rules look for loading, error, and empty branches. Mutation rules look for pending feedback and empty catches. Form rules look for submitting or disabled behavior. A finding includes a file and line so you can inspect the source rather than guessing what the scanner saw.\n\nThe repository's recommended repair order is routes, queries, mutations, and forms. For example, a Next.js route can inherit an app/loading.tsx, while a query component should expose loading, error, and empty states near the query result. A scanner finding is a prompt to review the code, not an automatic patch. The README documents a GitHub Actions composite action as well as a direct npx example.\n\nA minimal workflow step is: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npx unhappypath . --min-score 75 The current repository's action.yml invokes npx --yes unhappypath@0.1.0 and accepts path, min-score, and format inputs. If you use that action, review the pinned version and its source before trusting it in a production workflow. The repository also documents the composite action form: - uses: paladini/unhappypath@v1 with: path: .\n\nmin-score: \"75\" The two examples have different versioning behavior. The direct command from the README uses the package name without a version, while the composite action currently calls 0.1.0. Check the project's release status before adopting either form. At the time of this tutorial, no GitHub release or tag was published.\n\nThe scanner combines two kinds of static checks. A route scanner inspects Next.js App Router files such as page.tsx, loading.tsx, error.tsx, and not-found.tsx. A code scanner uses the TypeScript AST to inspect patterns such as query hooks, fetch calls inside effects, asynchronous click handlers, and forms. That design makes the result deterministic and local.\n\nThe same source tree can produce the same report without model tokens or external service availability. It also means the tool cannot prove runtime behavior. It does not run a browser, simulate a slow network or a server error, judge the quality of copy, or replace end-to-end tests. Its documented blind spots include deeply nested child-component handling and limited analysis of asynchronous Server Components.\n\nSecurity boundaries matter too. The scanner reads files from the path you give it and writes reports or badges only when you request those outputs. It does not claim to validate authorization, input handling, secrets, dependencies, or server-side security. Keep those checks in their appropriate tools and tests.\n\nNot according to the current documentation. Its route rules target the Next.js App Router, while its code rules inspect selected TypeScript and React patterns. Vue, Nuxt, SvelteKit, and Remix route conventions are listed as future work. No.\n\nIt means the current rules found no missing signals in the scanned source. A score does not evaluate visual design, copy, runtime failures, accessibility quality, performance, or business behavior. The README documents npx unhappypath /path/to/your-next-app as the future npm option. The current repository also provides a source checkout path that works today.\n\nVerify package publication and version availability before depending on an unpinned command. unhappypath is most useful as an early, deterministic review pass after an AI-assisted implementation. Build it from a known commit, scan the application, inspect each finding, and combine the result with runtime tests and human review. Treat the score as a prioritized checklist rather than a proof of readiness.\n\nWhat is the most valuable unhappy-path check for your team: route boundaries, data states, mutation feedback, or form submission behavior? Disclosure: This article was prepared with AI assistance. The repository documentation, package metadata, current commit, public GitHub metadata, and local commands described here were checked before publication.\n\n## Key Takeaways\n\n- •unhappypath is a small open-source CLI that scans source code for several of these missing UI states.\n- •This story was reported by **Dev.to** , covering developments in the**dev** space.\n- •AI advancements continue to reshape industries — read the full article on Dev.to for complete coverage.\n\n📖 Continue reading the full article:\n\n[Read Full Article on Dev.to →](https://dev.to/paladini/find-missing-loading-and-error-states-in-nextjs-with-unhappypath-amn)", "url": "https://wpnews.pro/news/find-missing-loading-and-error-states-in-next-js-with-unhappypath", "canonical_source": "https://ainexusdaily.vercel.app/article/2026-11-01-find-missing-loading-and-error-states-in-nextjs-with-unhappypath", "published_at": "2026-11-01 12:38:09+00:00", "updated_at": "2026-11-01 12:51:02.587665+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["unhappypath", "Next.js", "React", "Node.js", "TypeScript", "npm", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/find-missing-loading-and-error-states-in-next-js-with-unhappypath", "markdown": "https://wpnews.pro/news/find-missing-loading-and-error-states-in-next-js-with-unhappypath.md", "text": "https://wpnews.pro/news/find-missing-loading-and-error-states-in-next-js-with-unhappypath.txt", "jsonld": "https://wpnews.pro/news/find-missing-loading-and-error-states-in-next-js-with-unhappypath.jsonld"}}