{"id":14227,"library":"vfile-find-down","title":"vfile-find-down","description":"vfile-find-down is a utility for the vfile ecosystem, designed to locate one or multiple files by recursively searching the file system downwards from a given path. It processes files into `VFile` objects but does not populate their content, suggesting the use of `to-vfile` for actual file reading. Currently at version 7.1.0, the package maintains an active release cadence, with major versions introducing significant changes like the move to ESM and stricter Node.js requirements. It serves as a complementary tool to `vfile-find-up`, which handles upward directory traversal, making it suitable for scenarios like finding all Markdown files within a project directory rather than configuration files in parent directories.","status":"active","version":"7.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/vfile/vfile-find-down","tags":["javascript","vfile","vfile-util","util","utility","virtual","file","walk","find","typescript"],"install":[{"cmd":"npm install vfile-find-down","lang":"bash","label":"npm"},{"cmd":"yarn add vfile-find-down","lang":"bash","label":"yarn"},{"cmd":"pnpm add vfile-find-down","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core data structure for representing files and messages, integral to the vfile ecosystem as this utility returns `VFile` objects.","package":"vfile","optional":false},{"reason":"Commonly used to read file contents into the VFile `value` property, as `vfile-find-down` only locates files without reading their contents.","package":"to-vfile","optional":true}],"imports":[{"note":"'vfile-find-down' has been an ESM-only package since v6.0.0, requiring Node.js 16+ since v7.0.0. CommonJS 'require' will not work for direct imports.","wrong":"const findDown = require('vfile-find-down')","symbol":"findDown","correct":"import { findDown } from 'vfile-find-down'"},{"note":"The `findDownAll` function was named `findDown` in versions prior to v7.0.0. This package is ESM-only since v6.0.0.","wrong":"const findDownAll = require('vfile-find-down').findDownAll","symbol":"findDownAll","correct":"import { findDownAll } from 'vfile-find-down'"},{"note":"'Test' is a TypeScript type definition and should be imported using 'import type' for type-only imports, especially in environments configured for isolated modules.","wrong":"import { Test } from 'vfile-find-down'","symbol":"Test","correct":"import type { Test } from 'vfile-find-down'"}],"quickstart":{"code":"import { findDown } from 'vfile-find-down'\nimport { toVFile } from 'to-vfile'\nimport path from 'node:path'\nimport process from 'node:process'\n\nasync function run() {\n  const rootDir = process.cwd();\n  // Assuming there's a readme.md in the current or a sub-directory for this example\n  // To make it runnable, ensure a '.md' file exists in the current directory or a subdirectory.\n  // For testing purposes, you might create a temporary file:\n  // await fs.promises.writeFile(path.join(rootDir, 'temp.md'), '# Hello');\n\n  // Find the first markdown file downwards from the current directory.\n  const firstMdFile = await findDown('.md', rootDir);\n\n  if (firstMdFile) {\n    console.log('Found first Markdown file:', firstMdFile.history[0]);\n\n    // To read its content, use toVFile (optional dependency)\n    const fileWithContent = await toVFile.read(firstMdFile.history[0]);\n    console.log('Content of the file (first 50 chars):', fileWithContent.value?.toString().substring(0, 50));\n  } else {\n    console.log('No Markdown files found.');\n  }\n\n  // Example for finding all markdown files\n  const allMdFiles = await findDown('.md', rootDir);\n  if (Array.isArray(allMdFiles) && allMdFiles.length > 0) {\n    console.log('\\nAll Markdown files found:');\n    allMdFiles.forEach(file => console.log(file.history[0]));\n  }\n}\n\nrun().catch(console.error);","lang":"typescript","description":"Demonstrates how to use `findDown` to locate the first Markdown file in the current directory or its subdirectories and how to optionally read its content using `to-vfile`."},"warnings":[{"fix":"Ensure your Node.js environment is version 16 or higher. Update Node.js if necessary.","message":"Version 7.0.0 changed the minimum Node.js requirement to Node.js 16.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Migrate your import statements from `const pkg = require('pkg')` to `import { pkg } from 'pkg'`.","message":"Version 6.0.0 converted `vfile-find-down` to an ES module (ESM-only), deprecating CommonJS `require()`.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Update your code to use the new function names: `findDown` for finding the first file, and `findDownAll` for finding all files.","message":"Version 7.0.0 renamed the API functions: `findDownOne` was renamed to `findDown`, and `findDown` was renamed to `findDownAll`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"If you are using the callback API, update your logic to expect and return an object like `{ break: true, include: true }` instead of symbol combinations.","message":"Version 7.0.0 changed the callback return value from bitwise symbols (e.g., `CONTINUE | BREAK`) to a plain result object with `break`, `include`, `skip` boolean fields.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Avoid using undocumented or private APIs. Only use the officially exported identifiers like `findDown` and `findDownAll`.","message":"Version 7.0.0 changed to use an `export` map, which means accessing undocumented or private internal APIs may no longer work.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"If you need to access the file's content, use `to-vfile` (e.g., `toVFile.read(vfile)`) after finding the `VFile`.","message":"The `vfile-find-down` utility only locates files and populates `VFile` objects with path information; it does not read file contents into the `file.value` property by default.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'7.1.0':60 'activ':65 'actual':54 'cadenc':67 'chang':73 'complementari':87 'configur':115 'content':45 'current':57 'design':16 'directori':97,112,119 'downward':29 'ecosystem':15 'esm':78 'file':22,27,36,55,108,116,128 'find':3,7,92,105,130 'given':32 'handl':95 'introduc':71 'javascript':120 'like':74,104 'locat':18 'maintain':63 'major':69 'make':99 'markdown':107 'move':76 'multipl':21 'node.js':81 'object':39 'one':19 'packag':62 'parent':118 'path':33 'popul':43 'process':35 'project':111 'rather':113 'read':56 'recurs':24 'releas':66 'requir':82 'scenario':103 'search':25 'serv':84 'signific':72 'stricter':80 'suggest':46 'suitabl':101 'system':28 'to-vfil':50 'tool':88 'travers':98 'typescript':131 'upward':96 'use':48 'util':11,124,125,126 'version':59,70 'vfile':2,6,14,38,52,91,121,123 'vfile-find-down':1,5 'vfile-find-up':90 'vfile-util':122 'virtual':127 'walk':129 'within':109","created_at":"2026-04-20T01:58:36.193854+00:00","updated_at":"2026-04-20T01:58:36.193854+00:00","problems":[{"fix":"Update your import statement to use ES module syntax: `import { findDown } from 'vfile-find-down';` and ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to import `vfile-find-down` using CommonJS `require()` syntax in a Node.js environment, but the package is ESM-only since v6.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/vfile-find-down/index.js from ... not supported."},{"fix":"If you intended to find all files, change your call to `findDownAll`. If you intended to find a single file and were using `findDownOne`, you can now use `findDown`.","cause":"This error often occurs after upgrading to v7.0.0 if you were previously using `findDown` to find all files. The `findDown` function was renamed to `findDownAll`, and `findDownOne` was renamed to `findDown`.","error":"TypeError: (0, vfile_find_down_1.findDown) is not a function"},{"fix":"Ensure you pass a valid string or array of strings (or `URL` objects) as the `paths` argument, specifying where to start the search. By default, it uses `process.cwd()` if omitted, but explicit undefined might cause issues.","cause":"The `paths` argument for `findDown` or `findDownAll` was not provided or was `undefined`. This often happens when the second argument to `findDown` (which is `paths`) is missing or invalid.","error":"TypeError: Path must be a string. Received undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/vfile/vfile-find-down","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vfile-find-down","openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}