Find the first file matching a given pattern in the current directory or the nearest ancestor directory, with support for both CommonJS and ESM, and extended matching capabilities including RegExp, symlink control, and custom matchers callback.
💡 Useful for finding files or folders (like
package.json,.git, or config files) by walking upward from a starting directory.
npm install @yukiakai/find-upWorks with both require() and import thanks to dual CJS/ESM build.
import { findUp } from '@yukiakai/find-up'
// Find 'package.json' starting from current directory and walking upward
const path = findUp('package.json')
console.log(path)findUp(['pnpm-lock.yaml', 'yarn.lock', 'package-lock.json'])findUp(/^config\..*\.json$/)// Return full path including matched folder name
findUp(['node_modules', 'dist'], {
type: 'folder',
includeMatchedPath: true
})
// → /root/project/node_modulesimport fs from 'node:fs'
findUp('config.json', {
matcher: (path) => {
const content = fs.readFileSync(path, 'utf8')
// Return true to accept (stop searching), false to continue searching.
return true
}
})See docs: https://yukiakai212.github.io/find-up/
findUp(
name: string | RegExp | (string | RegExp)[],
options?: FindUpOptions
): string | undefined| Name | Type | Default | Description |
|---|---|---|---|
basedir |
string |
process.cwd() |
Directory to start searching from |
matcher |
(path: string) => () |
– | Called when a matching file is found. Return false to skip. |
type |
file | folder |
file |
Whether to match files or directories |
includeMatchedPath |
boolean |
false |
If true, returns full path including the matched name |
allowSymlinks |
boolean |
true |
Whether to allow matching symlinks |
stopAt |
string | string[] |
- | Stop searching when encountering these folders |
- ✅ Supports both CommonJS and ESM
- ✅ Supports
string,string[],RegExp,RegExp[] - ✅ Supports stop at
- ✅ File or folder matching
- ✅ Optional symlink filtering
- ✅ Custom matcher callback — inspect file content, metadata, or path before accepting match
- ✅ TypeScript types included
- ✅ Optional: return full matched path (includeMatchedPath)
const gitFolder = findUp('.git', { type: 'folder' })
if (gitFolder) {
console.log('Found .git at:', gitFolder)
}| Feature | @yukiakai/find-up | find-up | findup-sync |
|---|---|---|---|
| Supports CJS & ESM | ✅ | ❌ (ESM only) | ✅ (CJS only) |
| Supports RegExp | ✅ | ❌ | ✅ |
| Supports array of names/patterns | ✅ | ✅ | ✅ |
| File/folder type filtering | ✅ | ✅ | ❌ |
| Matcher can read file content | ✅ | ❌ | ❌ |
| Supports Symlinks | ✅ | ✅ | ❌ |
| Zero dependency | ✅ | ❌ | ❌ |
See full release notes in CHANGELOG.md
MIT © yukiakai