Skip to main content
kRouter
All posts
How kRouter works

Two API routes that never shipped, because a filter matched on a name

A build filter dropped directories called "logs". Next compiles /api/usage/logs into a directory called logs. The route was deleted on its way into the package, every check stayed green, and one endpoint had never shipped in any version.

Kodelyth · The team behind kRouter
7 min read

A user on a current release hit this:

Error: Cannot find module
'/opt/homebrew/lib/node_modules/@sifxprime/krouter/app/.next-cli-build/
 server/app/api/pxpipe/logs/route.js'
  at Module._resolveFilename (node:internal/modules/cjs/loader:1475:15)

The route exists in the source tree. It compiles. It works in development. It is present in the build output on the machine that produced the package. It is not in the package.

One filter, two meanings for one word

The CLI build copies the compiled Next output into the published npm package through an exclusion filter. The filter matched on basename:

function shouldExclude(name) { /* ... */ return name === pattern; }

Among its patterns is logs, meaning a runtime log directory — the sort of thing that accumulates beside a running app and should never be shipped to users.

Next compiles an API route at src/app/api/<x>/logs/route.js into server/app/api/<x>/logs/route.js.

A directory named logs.

So the copy deleted it. The word logs is a runtime artefact at the top of a package and a perfectly ordinary URL segment inside compiled route output, and a filter that only sees a basename cannot tell those apart. It saw the name it was told to drop and dropped it.

Every check stayed green, because every check ran against the source tree or the local build — neither of which the filter touches. The filter runs between "the build is correct" and "the package is published," and nothing was looking at the output of that step.

How long

Diffing a local build against the installed package found exactly two casualties out of 188 routes:

RouteStatus
/api/pxpipe/logsadded in v0.5.111, broken ever since
/api/usage/logspresent since the initial release — never shipped once, in any version

That second line is the one worth sitting with. Not a regression. Not something that broke in an upgrade. An endpoint that had been in the source tree for the entire life of the project, compiled correctly every single time, and had never once existed in a published package.

Confirmed against the published 0.5.191 tarball independently: zero logs routes present, against 304 other API files.

The fix has to distinguish by place, not by name

The naive repair is to remove logs from the exclusion list. That ships runtime log directories to every user.

The word genuinely means two different things depending on where it appears, so the filter has to know where it is. The patterns now split into two sets:

  • Excluded everywhere: names that are never a route segment — sharp, .env*, *.nft.json, and .build-home. That last one is a secret leak rather than a bloat problem: the build runs with HOME pointed at a workspace directory so it cannot touch the real one, and standalone tracing happily copied it into the bundle, shipping a generated jwt-secret that was identical for everyone who installed it. It stays excluded in every location, route output included.
  • Excluded outside compiled route output: logs, tmp. Ordinary words that are runtime artefacts at the top of a package and legitimate URL segments under server/app/.

shouldExclude now takes the directory being copied, not just the entry name, and spares anything under server/app/.

One detail in that check is load-bearing:

const COMPILED_ROUTES = `${path.sep}server${path.sep}app${path.sep}`;
return (path.resolve(srcDir) + path.sep).includes(COMPILED_ROUTES);

The trailing separator is appended before the test so that a directory which is server/app matches too. Its immediate children are route segments, so server/app/logs has to be protected as much as server/app/api/usage/logs. Without that append, the top level of the route tree would be the one place still unprotected.

The test that should have existed

Nothing compared the routes that exist against the routes that ship. That absence is the actual bug; the filter was just where it showed up.

So there is now a test that walks every API route in the source tree, simulates the copy the way the build performs it — segment by segment, each with its parent directory — and fails naming any route that would not survive:

the bundle would ship without these:
  /api/pxpipe/logs (segment "logs")
  /api/usage/logs (segment "logs")

Re-introducing the single-list filter makes it print exactly that. It also pins the two routes that were actually lost by name, so a future restructure cannot quietly stop exercising them.

Verified by running the real CLI build: both routes present, route count unchanged with nothing else dropped, and zero jwt-secret, machine-id, .build-home or *.sqlite* files in the output. The published package went from 152 API routes to 154, and the two added are precisely the two that had been missing.

The general version

This is a packaging bug, but the shape of it is not specific to packaging.

A filter that matches on a name rather than a path cannot distinguish a thing from a thing that happens to share its name. Given enough files, something will share the name. logs, tmp, build, dist, test, src, assets — every one of them is both a real artefact somewhere and a legitimate identifier somewhere else.

And the reason it survived for the life of the project is the more general lesson: there was a verification gap between the artefact that was tested and the artefact that was shipped. Everything green, every time, about a build that was not the thing users installed.

Kodelyth · The team behind kRouter

Published by Kodelyth, the team that builds kRouter. Posts are drafted with AI assistance and reviewed by a person before they go out. kRouter is free and MIT licensed.

Install kRouter