In an npm workspaces repo, `@rota/ui` imports `zone-kit` without declaring it; tests pass locally but consumers get Cannot find module, so why, and what catches it earlier?
answer
- works by accident
- shared copy at the root
- lookup walks up parent folders
- declare it with -w
- install-strategy=linked as a check
basics
~20 sHoisting put zone-kit in the root node_modules because a sibling or the root declares it, and Node.js finds it by walking up from packages/ui. Consumers get only declared dependencies. Declare it with npm install zone-kit -w @rota/ui; test under install-strategy=linked.
solid answer
~40 sUnder the default `install-strategy=hoisted`, npm installs shared dependencies once in the root `node_modules`. `@rota/date-rules` declares `zone-kit`, so it sits at the root, and an import from `packages/ui` finds it by walking up the folders; the missing line in `packages/ui/package.json` never shows. A project that installs `@rota/ui` gets only what that manifest declares, so `zone-kit` is absent and the import fails; inside the repository, a sibling changing its `zone-kit` version can break it too. The fix is to declare it where it is imported: `npm install zone-kit -w @rota/ui`, not in the root manifest, which `@rota/ui` does not ship. To catch the next one earlier, test with `--install-strategy=linked`, whose isolated layout exposes only declared dependencies. npm calls it one check, not a guarantee, because the root's own dependencies can still satisfy the import.
go deeper
Recall that every package you import must be listed in the importing package's own dependencies, even when it already works.
Explain how hoisting plus Node.js walking up parent folders lets an undeclared import resolve inside a workspace repo.
Diagnose why it passes locally and fails for consumers, fix it with npm install <pkg> -w, and name linked-strategy testing and its root blind spot.
Decide which guard the team relies on: linked-layout test runs, packing and installing in a clean project, or an import-versus-manifest lint, and what each misses.
## The symptom In the shift-rota repository, `packages/ui/src/shift-cell.js` imports a time-zone helper library, `zone-kit`, but `packages/ui/package.json` never lists it; only its sibling `@rota/date-rules`, which `@rota/ui` does not depend on, declares it. Locally every test passes and both apps build. Once `@rota/ui` is installed somewhere else, as a published package in another project or on its own in a clean folder, loading it fails with Node.js's `Cannot find module 'zone-kit'`. Nothing in the code changed between the two runs; only the `node_modules` around it did. ## Why it works inside the repository: hoisting Under npm's default **`install-strategy=hoisted`**, a root `npm install` builds one tree for all workspaces and puts every dependency that does not conflict **once, in the root `node_modules`**. `@rota/date-rules` declares `zone-kit`, so `zone-kit` lands at the root: ``` . +-- node_modules | +-- zone-kit (hoisted, declared by date-rules) | +-- @rota/date-rules -> ../packages/date-rules | `-- @rota/ui -> ../packages/ui `-- packages +-- date-rules/package.json "zone-kit": "^3.1.0" `-- ui/package.json (no zone-kit) ``` When code in `packages/ui` imports `zone-kit`, the lookup goes like this: 1. Node.js looks for `packages/ui/node_modules/zone-kit` and finds nothing, because `@rota/ui` declares no such dependency. 2. It moves up one folder and tries `packages/node_modules/zone-kit`, which does not exist either. 3. It reaches the repository root and finds the hoisted `node_modules/zone-kit`, installed there for `@rota/date-rules`. The same happens if the **root** `package.json` lists the library. Either way, the import resolves by accident, and npm documents this as an undeclared, or **"phantom"**, dependency: it passes your own build silently, then fails for anyone who installs the package on its own. To see why a package is present at all, `npm explain zone-kit` prints the chain of dependencies that caused it to be installed; if `@rota/ui` is not among them, the import is borrowed. ## Why it fails for a consumer A project that installs `@rota/ui` gets exactly what `@rota/ui`'s own manifest declares, plus their dependencies. `zone-kit` is not declared, so it is not installed for it, and the import fails. A consumer may even get lucky for a while, if something else in their tree happens to pull in `zone-kit`, which makes the bug intermittent across consumers. The trap can also bite **inside** the repository: if `@rota/date-rules` moves to an incompatible major of `zone-kit`, or stops using it, the copy `@rota/ui` silently relied on changes version or disappears. ## Fixing it: declare it where it is imported The fix is a declaration in the workspace that does the importing: ```bash npm install zone-kit -w @rota/ui ``` That writes `zone-kit` into `packages/ui/package.json` and updates the root lockfile. If both workspaces use compatible ranges, the install layout barely changes: there is still one hoisted copy, but now `@rota/ui` is entitled to it. Moving the library into the root `package.json` instead does **not** fix it: the root manifest is not part of what `@rota/ui` ships. ## Catching the next one before it ships - **Develop and test under `install-strategy=linked`.** npm's linked strategy installs packages into `node_modules/.store` and links them in place, unhoisted, so each package sees only its declared dependencies, and an undeclared import fails during development. npm's own developer guide recommends exactly this for package authors: `npm install --install-strategy=linked`, then `npm test`. - **Know its limit.** npm says plainly that it is one check, not a guarantee: a dependency still satisfied by a `devDependency`, or by the **workspace root's** `node_modules`, can resolve for you and still be missing for whoever installs your package. - **Install the packed package somewhere empty.** Packing the workspace and installing that tarball into a scratch project outside the repository exercises exactly what a consumer gets. - **Review imports against the manifest.** A lint rule or review habit that flags imports missing from the importing package's own `dependencies` catches the class directly. ## Hoisted versus linked, side by side | | `hoisted` (default) | `linked` | |---|---|---| | Where dependencies go | once at the root where possible | `node_modules/.store`, linked in place | | Undeclared import of a hoisted package | resolves silently | fails during development | | Root's own dependencies | visible to every workspace | still visible, so still a blind spot | | Purpose | the default layout | npm's suggested check for package authors | Signs that a workspace repository has this problem already: - an import in a workspace's source whose package name never appears in that workspace's `package.json`; - a library that only the root `package.json` declares, although the root itself contains little or no code; - a consumer report of a missing module that nobody can reproduce inside the repository. The point to carry into an interview: a green build inside a workspace repository proves the **repository's** tree is complete, not that each workspace's **manifest** is.
- Why doesn't `--install-strategy=linked` catch every undeclared dependency?It hides only what other packages declared. A library listed in the root `package.json`, or one satisfied by a `devDependency`, can still resolve during development and be missing for a consumer. npm's developer guide calls it one check, alongside auditing what the published package actually imports.
- Would moving `zone-kit` into the root package.json fix it for consumers?No. The root manifest is not part of what `@rota/ui` ships, so consumers still never get the library. It also makes the bug harder to catch, because the root's dependencies stay visible to every workspace even under the linked strategy. Declare it in `packages/ui/package.json`.
- How could this break inside the repository even though nobody touched `@rota/ui`?`@rota/ui` silently uses whichever `zone-kit` copy is hoisted for `@rota/date-rules`. If date-rules moves to an incompatible major or drops the library, the hoisted copy changes version or disappears, and `@rota/ui` breaks with no change of its own.
It is like borrowing the stapler from the office's shared supply cupboard: it is always there at work, so you never buy one, and the day you work from home it is missing. The fix is to put a stapler on your own list.
- If tests pass in the monorepo, each package's declared dependencies are complete.
- Listing the library in the root package.json fixes it for consumers.
- Consumers get it anyway, because zone-kit is recorded in the root lockfile.
- install-strategy=linked catches every undeclared dependency.
- Hoisting copies each dependency into every workspace's own node_modules.