escalade

library3.2.0jsnpmunverified

escalade is a minimalistic and performant utility designed for synchronously or asynchronously traversing up parent directories to locate a specific file or directory. It continuously executes a provided callback function for each directory in the ancestry chain until the callback returns a truthy value, at which point the absolute path to the found item is returned, or until the system root directory is reached. The current stable version is `3.2.0`, with releases occurring a few times a year for patches, minor features, and ecosystem compatibility updates (e.g., Deno support, TypeScript resolution fixes). Its primary differentiators are its extremely small footprint (183-210 bytes gzipped) and its clear separation into synchronous and asynchronous execution modes, catering to a wide range of Node.js and Deno environments. It strictly searches direct parent directories and does not explore sibling directories of parents.

devops

npm install escalade

github ↗package ↗

INSTALL

IMPORT

SIG · ESCALADE

escalade

devopsjavascriptv3.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

escalade

✓ import escalade from 'escalade';

✗ const escalade = require('escalade');

This is the primary (async) ES Module export. For CommonJS, use `require('escalade')`. Since v3.2.0, separate TypeScript definitions are provided for ESM and CJS.

escalade (sync version)

✓ import escaladeSync from 'escalade/sync';

✗ const escaladeSync = require('escalade'); // Wrong path import escaladeSync from 'escalade'; // Not the sync version

To use the synchronous version, import from the specific subpath `'escalade/sync'`. This is available for both ES Modules and CommonJS (`require('escalade/sync')`).

escalade (CommonJS)

✓ const escalade = require('escalade');

✗ import escalade from 'escalade';

This is the primary (async) CommonJS export. Ensure your environment supports `exports` map resolution or use an older Node.js version where CJS resolution was default.

This example demonstrates how to use the async `escalade` function to traverse parent directories from a given starting path to find the nearest `package.json` file. It then logs the path and the package name if found.

import { join } from 'path'; import escalade from 'escalade'; import { fileURLToPath } from 'url'; const __filename = fileURLToPath(import.meta.url); const __dirname = join(__filename, '..'); // Assuming a file structure like: // project-root/ // package.json // src/ // index.js // features/ // my-feature.js const startPath = join(__dirname, 'features', 'my-feature.js'); console.log(`Starting search from: ${startPath}`); async function findPackageJson() { const pkgPath = await escalade(startPath, (dir, names) => { console.log(` Searching in: ${dir}`); if (names.includes('package.json')) { return 'package.json'; } }); if (pkgPath) { console.log(`Found package.json at: ${pkgPath}`); const packageJson = await import(pkgPath, { assert: { type: 'json' } }); console.log(`Package name: ${packageJson.default.name}`); } else { console.log('package.json not found in parent directories.'); } } findPackageJson().catch(console.error);

Debug

Known issues

gotchaescalade strictly traverses direct parent directories and will not explore sibling directories of any parent. Its search scope is limited to the direct ancestral chain.

fix

If you need to search sibling directories or a broader filesystem scope, a different utility or manual directory traversal logic is required.

affects: >=3.0.0

breakingIn `v3.2.0`, separate TypeScript definitions for ESM and CommonJS were introduced. Previously, only ESM definitions were shipped, which could cause tool or resolution ambiguity in certain TypeScript configurations. While a fix, it might require adjustments for existing TypeScript users.

fix

Ensure your `tsconfig.json`'s `moduleResolution` and `module` options are correctly configured for your environment (e.g., `Node16` or `NodeNext`). This change primarily resolves issues rather than introducing new ones, but older tooling might need updates.

affects: >=3.2.0

gotchaUsers running Node.js versions 13.0 through 13.6 (inclusive) might have encountered issues with `require()` due to early, partial support of the `exports` map behavior in those specific Node.js releases. This was patched in `v3.1.1`.

fix

Update to `escalade@3.1.1` or newer. Alternatively, avoid Node.js versions 13.0-13.6 if using older `escalade` versions with CommonJS `require()`.

affects: >=3.0.0 <3.1.1

gotchaThe `escalade/sync` module is not Promise-based. Attempting to `await` its return value will result in a runtime error because the function does not return a Promise.

fix

When importing from `escalade/sync`, remove any `await` keywords and handle the return value directly, as it is synchronous. For asynchronous operations, import from the default `'escalade'` path.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: escalade(...).then is not a function

Attempting to use `await` or `.then()` on the synchronous `escalade/sync` function.

fix

Ensure you are importing the correct version of escalade. If you need asynchronous behavior, import from `'escalade'`. If you intend to use the synchronous version from `'escalade/sync'`, remove `await` keywords as it returns its value directly.

TS2307: Cannot find module 'escalade' or its corresponding type declarations.

TypeScript compilation issue due to incorrect module resolution or outdated type definitions.

fix

Ensure your `tsconfig.json` has appropriate `moduleResolution` settings (e.g., `Node16` or `NodeNext`). If using `escalade@3.1.2`, ensure `nodenext` is configured. For `escalade@3.2.0` and newer, separate ESM/CJS type definitions are provided, which should resolve most ambiguity issues. Clear `node_modules` and reinstall if issue persists.

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'escalade/sync' imported from ...

Node.js or build tool failing to resolve the `escalade/sync` subpath export, often due to an environment not fully supporting `exports` maps.

fix

Verify your Node.js version is compatible (>=12.17.0 for stable `exports` support). Ensure bundlers or module loaders are configured to handle `exports` maps. Updating `escalade` to the latest version (`v3.1.1` fixed some specific Node 13.x issues) can also help.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/lukeed/escalade ↗

packagehttps://www.npmjs.com/package/escalade ↗