vfile-find-up

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES module /path/to/node_modules/vfile-find-up/index.js from /your/project/index.js not supported.

  cause Attempting to import `vfile-find-up` using CommonJS `require()` syntax in a non-ESM environment.
  fix Switch to ES Module `import` syntax (`import { findUp } from 'vfile-find-up';`) and ensure your Node.js project is configured for ESM.

• TypeError: vfile_find_up_1.findUp is not a function

  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).
  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`.

• Error: vfile-find-up requires Node.js 16 or later.

  cause Running `vfile-find-up@7.0.0` or later on an unsupported Node.js version (older than 16).
  fix Upgrade your Node.js environment to version 16 or higher to meet the package's minimum requirements.

Warnings

• breaking 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`.
  Fix: Update your code to use `findUpAll` for finding all files and `findUp` for finding the first file.
• breaking 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 }`.
  Fix: Refactor custom `test` functions to return an object with `break` and `include` boolean fields instead of bitwise symbols.
• breaking Version 7.0.0 increased the minimum Node.js requirement to Node.js 16 or higher.
  Fix: Ensure your Node.js environment is upgraded to version 16 or newer before deploying applications using this package.
• breaking Version 6.0.0 made the package ESM-only. CommonJS `require()` is no longer supported.
  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`).
• gotcha 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`.
  Fix: After finding a file, pass its path to `toVFile.read(file.path)` to get a `VFile` with its content loaded.

Install

• npm install vfile-find-up npm
• yarn add vfile-find-up yarn
• pnpm add vfile-find-up pnpm

Imports

• findUp
  wrong:

  const findUp = require('vfile-find-up');

  correct:

  import { findUp } from 'vfile-find-up';

  Package is ESM-only since v6.0.0. Also, `findUp` was previously `findUpOne` before v7.0.0.
• findUpAll
  wrong:

  import findUpAll from 'vfile-find-up';

  correct:

  import { findUpAll } from 'vfile-find-up';

  Package is ESM-only since v6.0.0 and `findUpAll` is a named export. This function was previously named `findUp` before v7.0.0.
• Callback
  wrong:

  import { Callback } from 'vfile-find-up';

  correct:

  import type { Callback } from 'vfile-find-up';

  Import types using `import type` to avoid bundling unused runtime code, especially for type-only exports like `Callback`.

Quickstart

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

import { findUp, findUpAll } from 'vfile-find-up';
import { toVFile } from 'to-vfile'; // Recommended for reading file content

async function runFindUpExamples() {
  const currentDir = process.cwd();

  // Find the first package.json upwards
  console.log('--- Finding single package.json ---');
  try {
    const pkgFile = await findUp('package.json', currentDir);
    if (pkgFile) {
      console.log(`Found package.json at: ${pkgFile.path}`);
      // To read its content, use to-vfile
      const fullPkgFile = await toVFile.read(pkgFile.path);
      console.log('Content (first 100 chars):', fullPkgFile.value?.toString().substring(0, 100) + '...');
    } else {
      console.log('No package.json found upwards.');
    }
  } catch (error) {
    console.error('Error finding package.json:', error);
  }

  // Find all .md files upwards (demonstrating custom test function)
  console.log('\n--- Finding all .md files upwards ---');
  try {
    const mdFiles = await findUpAll((file) => file.extname === '.md', currentDir);
    if (mdFiles.length > 0) {
      console.log(`Found ${mdFiles.length} markdown files:`);
      mdFiles.forEach((file) => console.log(`- ${file.path}`));
    } else {
      console.log('No markdown files found upwards.');
    }
  } catch (error) {
    console.error('Error finding markdown files:', error);
  }
}

runFindUpExamples();