or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-find-cache-dir

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/find-cache-dir@5.0.x

To install, run

npx @tessl/cli install tessl/npm-find-cache-dir@5.0.0

index.mddocs/

Find Cache Dir

Find Cache Dir provides a utility for finding the common standard cache directory location in Node.js projects. It implements the standardized cache directory structure used by popular tools like nyc, AVA, Storybook, and babel-loader, automatically locating the appropriate cache directory and handling directory creation with proper write permission checks.

Package Information

  • Package Name: find-cache-dir
  • Package Type: npm
  • Language: JavaScript (ES Module)
  • Installation: npm install find-cache-dir

Core Imports

import findCacheDirectory from "find-cache-dir";

For CommonJS projects:

// Note: This package is ES Module only. CommonJS usage requires dynamic import
const { default: findCacheDirectory } = await import("find-cache-dir");

Basic Usage

import findCacheDirectory from "find-cache-dir";

// Basic usage - finds cache directory for your package
const cacheDir = findCacheDirectory({ name: "my-package" });
console.log(cacheDir);
// => "/user/project/node_modules/.cache/my-package"

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

// Override with environment variable
process.env.CACHE_DIR = "/custom/cache";
const cacheDir = findCacheDirectory({ name: "my-package" });
// => "/custom/cache/my-package"

Capabilities

Cache Directory Resolution

Finds the cache directory using the given options, following the standardized cache directory structure.

/**
 * 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 found
 */
function findCacheDirectory(options: Options): string | undefined;

interface Options {
  /** Should be the same as your project name in package.json (required) */
  readonly name: string;
  
  /** 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 */
  readonly files?: string[];
  
  /** 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;
}

Usage Examples:

import findCacheDirectory from "find-cache-dir";

// Basic usage with package name
const cacheDir = findCacheDirectory({ name: "unicorns" });
// => "/user/path/node_modules/.cache/unicorns"

// Search from specific files for common parent
const cacheDir = findCacheDirectory({
  name: "my-tool",
  files: ["src/index.js", "test/test.js", "lib/utils.js"]
});
// Uses common parent directory of the provided files

// Start search from custom directory
const cacheDir = findCacheDirectory({
  name: "my-tool",
  cwd: "/custom/project/path"
});

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

// Environment variable override
process.env.CACHE_DIR = "/tmp/custom-cache";
const cacheDir = findCacheDirectory({ name: "my-tool" });
// => "/tmp/custom-cache/my-tool"

Algorithm Details

The cache directory resolution follows this algorithm:

  1. Environment Variable Check: If CACHE_DIR environment variable is set and not equal to 'true', 'false', '1', or '0', uses $CACHE_DIR/{name} as the cache directory
  2. Working Directory Resolution: Determines the working directory from:
    • Common parent directory of files array (if provided)
    • cwd option (if provided)
    • process.cwd() (default)
  3. Package Directory Search: Searches upward from working directory to find nearest package.json file
  4. Node Modules Validation: Checks that node_modules directory exists or can be created with write permissions
  5. Cache Path Construction: Returns {packageDir}/node_modules/.cache/{name}

Error Handling

// Function throws TypeError for invalid files option
// Returns undefined for various failure conditions:
// - No package.json found in parent directories
// - node_modules directory is not writable
// - node_modules cannot be created due to permissions

The function throws a TypeError if the files option is provided but is not an array, with the message: Expected \files` option to be an array, got `${typeof files}`.. It returns undefined` (rather than throwing) when:

  • No package.json file is found by searching parent directories
  • The node_modules directory exists but is not writable
  • The node_modules directory doesn't exist and cannot be created due to permissions

Environment Variables

// CACHE_DIR: Override cache directory location
// Ignored if set to 'true', 'false', '1', or '0'

The CACHE_DIR environment variable provides a way to override the cache directory location. When set to a valid path (not 'true', 'false', '1', or '0'), the function will use $CACHE_DIR/{name} as the cache directory instead of the standard node_modules/.cache/{name} location.

Types

interface Options {
  readonly name: string;
  readonly files?: string[];
  readonly cwd?: string;
  readonly create?: boolean;
}