@yukiakai/find-up

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.

Installation

npm install @yukiakai/find-up

Works with both require() and import thanks to dual CJS/ESM build.

Usage

Basic usage

import { findUp } from '@yukiakai/find-up'

// Find 'package.json' starting from current directory and walking upward
const path = findUp('package.json')
console.log(path)

Match multiple names

findUp(['pnpm-lock.yaml', 'yarn.lock', 'package-lock.json'])

Match using RegExp

findUp(/^config\..*\.json$/)

Match folders instead of files

// Return full path including matched folder name
findUp(['node_modules', 'dist'], {
  type: 'folder',
  includeMatchedPath: true
})
// → /root/project/node_modules

Custom matcher callback

import 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
  }
})

API

See docs: API Docs

findUp(
  name: string | RegExp | (string | RegExp)[],
  options?: FindUpOptions
): string | undefined

Options

| 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 |

Features

• ✅ 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)

Example: Find .git folder

const gitFolder = findUp('.git', { type: 'folder' })
if (gitFolder) {
  console.log('Found .git at:', gitFolder)
}

Comparison

| 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 | ✅ | ❌ | ❌ |

Changelog

See full release notes in CHANGELOG.md

License

MIT © yukiakai