CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-find-cache-dir

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

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/find-cache-dir@5.0.x
Publish Source
CLI
Badge
tessl/npm-find-cache-dir badge