find-cache-directory

find-cache-directory is a tiny, focused Node.js utility that implements a naming convention originally standardized by the nyc and AVA projects: storing per-package cache data under node_modules/.cache/<package-name>. Rather than every tool inventing its own cache path, packages that adopt this convention become predictable and easy to clear in bulk with a single rm -rf ./node_modules/.cache.

Given an options object with at minimum a name, the function walks up from the current working directory (or a supplied cwd, or the common parent of a list of files) to find the nearest package.json, verifies that node_modules is writable, and returns the resolved cache path — optionally creating it. It also respects a CACHE_DIR environment variable for overriding the location entirely, which is useful in CI and testing.

What You Get

• A default export, findCacheDirectory(options), returning an absolute path string or undefined
• Automatic upward traversal to the nearest package.json via pkg-dir, so it works from any subdirectory
• A files option that derives the search root from the common parent of a list of file paths via common-path-prefix
• Support for the CACHE_DIR environment variable to override the resolved location, with sane handling of falsy string values like ‘false’ or ‘0’
• An optional create flag to synchronously make the directory before returning its path
• Full TypeScript type definitions (index.d.ts) validated with tsd

Common Use Cases

• Test runners and build tools (originally AVA and nyc) storing per-package intermediate/coverage cache data
• Bundlers and transform tools like babel-loader caching compiled output between builds
• Storybook caching build artifacts to speed up repeat builds
• Any CLI or library that wants a writable scratch directory scoped to the consuming project rather than the OS temp directory

Under The Hood

Architecture The entire implementation lives in a single ~65-line ESM module (index.js) exporting one default function with no internal class hierarchy or layering: it checks the CACHE_DIR environment variable first, then resolves a search directory from either the files option (via commonPathPrefix) or cwd, locates the nearest package.json using pkg-dir’s packageDirectorySync, confirms the corresponding node_modules directory is writable through small isWritable/getNodeModuleDirectory helpers, and finally joins and optionally creates the target path. There is no dependency injection or internal data flow beyond a handful of synchronous fs calls; the whole traversal logic hinges entirely on pkg-dir’s package-root resolution, so swapping or breaking that one dependency would immediately break every code path in the module.

Tech Stack A plain ESM Node.js module (“type”: “module”, engines >=20) with exactly two runtime dependencies: common-path-prefix for computing the shared parent of multiple file paths, and pkg-dir (also maintained by the same author) for locating the nearest package.json upward from a directory. There is no build step — index.js and index.d.ts ship directly as-is per the package.json files field. Dev tooling is ava for tests, tsd for type-definition testing, xo (an opinionated ESLint preset) for linting, and del/tempy for temp-directory test fixtures. CI runs the full test/lint/type-check suite on GitHub Actions against Node 20 and 22.

Code Quality test.js exercises the module with AVA across six focused cases: resolving from an explicit files list, from process.cwd, from an explicit cwd option, directory creation via the create flag, returning undefined when no package.json exists, and CACHE_DIR environment-variable handling including its falsy-string edge cases — using real temporary directories via tempy/del rather than mocks, so the traversal and filesystem logic is exercised end-to-end. Public types in index.d.ts are checked against real usage via index.test-d.ts and tsd. Linting runs through xo on every CI invocation. Error handling is minimal but appropriate for the module’s small surface: a single try/catch guards an fs.accessSync permission check, and one explicit TypeError is thrown for a malformed files option — there is no test file found for those thrown paths, but coverage of the primary resolution logic is thorough for the module’s size.

What Makes It Unique The package makes no claim to novel technique — its value is being the single, well-maintained reference implementation of a caching-directory naming convention that originated with nyc and AVA, since adopted by Storybook and babel-loader among others. Rather than each tool inventing its own cache-location scheme, depending on this package lets an ecosystem of otherwise-unrelated tools converge on one predictable, jointly-clearable location.