Blog Docs Log in Get started

tessl/npm-find-cache-directory

Finds the common standard cache directory location for Node.js projects

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Find Cache Directory

Find Cache Directory locates the standardized cache directory path for Node.js projects following the common pattern adopted by tools like nyc and AVA. It provides a consistent caching solution across different project structures and environments.

Package Information

Package Name: find-cache-directory
Package Type: npm
Language: JavaScript (ESM modules with TypeScript definitions)
Installation: npm install find-cache-directory

Core Imports

import findCacheDirectory from "find-cache-directory";

For TypeScript:

import findCacheDirectory, { type Options } from "find-cache-directory";

Basic Usage

import findCacheDirectory from "find-cache-directory";

// Find cache directory for your project
const cacheDir = findCacheDirectory({ name: 'my-app' });
//=> '/user/path/node_modules/.cache/my-app'

// Create the cache directory if it doesn't exist
const cacheDirCreated = findCacheDirectory({ 
  name: 'my-app', 
  create: true 
});

// Specify custom working directory
const customCacheDir = findCacheDirectory({ 
  name: 'my-app',
  cwd: '/path/to/project'
});

// Find common cache directory from multiple files
const filesCacheDir = findCacheDirectory({
  name: 'my-app',
  files: ['/path/to/file1.js', '/path/to/file2.js']
});

Algorithm

The cache directory resolution follows this algorithm:

Environment Variable: Checks CACHE_DIR environment variable (ignores values 'true', 'false', '1', '0')
Project Discovery: Finds the nearest package.json file starting from the working directory
Path Construction: Returns {projectRoot}/node_modules/.cache/{name}
Permission Validation: Ensures the cache directory location is writable
Optional Creation: Creates directory if create: true option is specified

Capabilities

Find Cache Directory

The main function that locates or creates a standardized cache directory path.

/**
 * Finds the cache directory using the given options.
 * 
 * The algorithm checks for the CACHE_DIR environmental variable and uses it 
 * if it is not set to 'true', 'false', '1' or '0'. If one is not found, it 
 * tries to find a package.json file, searching every parent directory of the 
 * cwd specified (or implied from other options). It returns a string containing 
 * the absolute path to the cache directory, or undefined if package.json was 
 * never found or if the node_modules directory is unwritable.
 * 
 * @param options - Configuration options for cache directory resolution
 * @returns Absolute path to cache directory or undefined if not resolvable
 */
export default function findCacheDirectory(options: Options): string | undefined;

Types

interface Options {
  /**
   * Should be the same as your project name in package.json.
   * Used as the subdirectory name within .cache/
   */
  readonly name: string;

  /**
   * An array of files that will be searched for a common parent directory.
   * This common parent directory will be used in lieu of the cwd option below.
   */
  readonly files?: string[];

  /**
   * The directory to start searching for a package.json from.
   * 
   * @default process.cwd()
   */
  readonly cwd?: string;

  /**
   * Create the directory synchronously before returning.
   * 
   * @default false
   */
  readonly create?: boolean;
}

Environment Variables

CACHE_DIR: When set to a directory path (not 'true', 'false', '1', '0'), overrides the default cache location algorithm. The cache directory will be ${CACHE_DIR}/${name}.

Error Handling

The function handles errors gracefully:

TypeError: Thrown if files option is provided but is not an array
Returns undefined when:
- No package.json file is found in the directory tree
- The node_modules directory is not writable
- Directory permissions prevent access to the cache location

Usage Examples

Testing with Custom Cache Directory

// Set environment variable for testing
process.env.CACHE_DIR = '/tmp/test-cache';
const testCacheDir = findCacheDirectory({ name: 'test-app' });
//=> '/tmp/test-cache/test-app'

Working with Multiple Files

// Find common parent directory for multiple files
const files = [
  '/project/src/component1.js',
  '/project/src/component2.js',
  '/project/tests/test1.js'
];

const cacheDir = findCacheDirectory({
  name: 'build-cache',
  files: files
});
//=> '/project/node_modules/.cache/build-cache'

Creating Cache Directory

// Ensure cache directory exists
const cacheDir = findCacheDirectory({
  name: 'my-tool',
  create: true  // Creates directory if it doesn't exist
});

if (cacheDir) {
  // Cache directory is ready to use
  console.log(`Cache directory: ${cacheDir}`);
} else {
  console.log('Could not resolve cache directory');
}

docs