{"id":12355,"library":"vfile-find-up","title":"vfile-find-up","description":"vfile-find-up is a utility within the vfile ecosystem designed to locate one or more files by traversing the file system upwards from a specified path. It operates on `vfile` objects, which standardize virtual file representation, making it suitable for unified processing workflows. The current stable version is 7.1.0, and the package maintains a steady release cadence, typically introducing major versions for breaking API changes or significant architectural shifts. Key differentiators include its tight integration with `vfile` for consistent file handling, its specific focus on *upward* directory traversal (contrasting with `vfile-find-down`), and its provision of both promise-based and traditional callback APIs, offering flexibility for asynchronous operations. It's particularly useful for locating configuration files or project roots.","status":"active","version":"7.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/vfile/vfile-find-up","tags":["javascript","vfile","vfile-util","util","utility","virtual","file","walk","find","typescript"],"install":[{"cmd":"npm install vfile-find-up","lang":"bash","label":"npm"},{"cmd":"yarn add vfile-find-up","lang":"bash","label":"yarn"},{"cmd":"pnpm add vfile-find-up","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only since v6.0.0. Also, `findUp` was previously `findUpOne` before v7.0.0.","wrong":"const findUp = require('vfile-find-up');","symbol":"findUp","correct":"import { findUp } from 'vfile-find-up';"},{"note":"Package is ESM-only since v6.0.0 and `findUpAll` is a named export. This function was previously named `findUp` before v7.0.0.","wrong":"import findUpAll from 'vfile-find-up';","symbol":"findUpAll","correct":"import { findUpAll } from 'vfile-find-up';"},{"note":"Import types using `import type` to avoid bundling unused runtime code, especially for type-only exports like `Callback`.","wrong":"import { Callback } from 'vfile-find-up';","symbol":"Callback","correct":"import type { Callback } from 'vfile-find-up';"}],"quickstart":{"code":"import { findUp, findUpAll } from 'vfile-find-up';\nimport { toVFile } from 'to-vfile'; // Recommended for reading file content\n\nasync function runFindUpExamples() {\n  const currentDir = process.cwd();\n\n  // Find the first package.json upwards\n  console.log('--- Finding single package.json ---');\n  try {\n    const pkgFile = await findUp('package.json', currentDir);\n    if (pkgFile) {\n      console.log(`Found package.json at: ${pkgFile.path}`);\n      // To read its content, use to-vfile\n      const fullPkgFile = await toVFile.read(pkgFile.path);\n      console.log('Content (first 100 chars):', fullPkgFile.value?.toString().substring(0, 100) + '...');\n    } else {\n      console.log('No package.json found upwards.');\n    }\n  } catch (error) {\n    console.error('Error finding package.json:', error);\n  }\n\n  // Find all .md files upwards (demonstrating custom test function)\n  console.log('\\n--- Finding all .md files upwards ---');\n  try {\n    const mdFiles = await findUpAll((file) => file.extname === '.md', currentDir);\n    if (mdFiles.length > 0) {\n      console.log(`Found ${mdFiles.length} markdown files:`);\n      mdFiles.forEach((file) => console.log(`- ${file.path}`));\n    } else {\n      console.log('No markdown files found upwards.');\n    }\n  } catch (error) {\n    console.error('Error finding markdown files:', error);\n  }\n}\n\nrunFindUpExamples();","lang":"typescript","description":"Demonstrates how to use `findUp` to locate the first `package.json` and `findUpAll` with a custom test function to find all markdown files, along with reading file content using `to-vfile`."},"warnings":[{"fix":"Update your code to use `findUpAll` for finding all files and `findUp` for finding the first file.","message":"Version 7.0.0 changed the API names. The previous `findUp` (which found all files) was renamed to `findUpAll`, and the previous `findUpOne` (which found the first file) was renamed to `findUp`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Refactor custom `test` functions to return an object with `break` and `include` boolean fields instead of bitwise symbols.","message":"Version 7.0.0 updated the expected return value for custom `test` functions. Instead of bitwise symbols (e.g., `EXIT`, `INCLUDE`), you must now return a plain object like `{ break: true, include: true }`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure your Node.js environment is upgraded to version 16 or newer before deploying applications using this package.","message":"Version 7.0.0 increased the minimum Node.js requirement to Node.js 16 or higher.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Migrate your consuming code to use ES Modules `import` syntax. If using Node.js, ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","message":"Version 6.0.0 made the package ESM-only. CommonJS `require()` is no longer supported.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"After finding a file, pass its path to `toVFile.read(file.path)` to get a `VFile` with its content loaded.","message":"This package returns `VFile` objects, but their `value` property (file content) is *not* populated by default. If you need to read the file content, you must explicitly use a utility like `to-vfile`.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Switch to ES Module `import` syntax (`import { findUp } from 'vfile-find-up';`) and ensure your Node.js project is configured for ESM.","cause":"Attempting to import `vfile-find-up` using CommonJS `require()` syntax in a non-ESM environment.","error":"Error [ERR_REQUIRE_ESM]: require() of ES module /path/to/node_modules/vfile-find-up/index.js from /your/project/index.js not supported."},{"fix":"If you were looking for all files, change `findUp` to `findUpAll`. If you were using `findUpOne`, change it to `findUp`. Check the API changes for `v7.0.0`.","cause":"After `v7.0.0`, the `findUp` function (which found all files) was renamed to `findUpAll`, and the old `findUpOne` became `findUp` (finding the first file).","error":"TypeError: vfile_find_up_1.findUp is not a function"},{"fix":"Upgrade your Node.js environment to version 16 or higher to meet the package's minimum requirements.","cause":"Running `vfile-find-up@7.0.0` or later on an unsupported Node.js version (older than 16).","error":"Error: vfile-find-up requires Node.js 16 or later."}],"ecosystem":"npm"}