{"id":12358,"library":"vfile-reporter","title":"vfile-reporter: Report Generator","description":"vfile-reporter is a utility package within the vfile ecosystem, designed to generate human-readable textual reports from one or more vfile instances. These reports summarize messages (warnings, errors, and info) that occurred during file processing, mimicking the output of tools like ESLint or esbuild. The current stable version is 8.1.1. The package maintains an active release cadence, with minor updates addressing fixes and features, and major versions typically aligning with Node.js LTS updates or breaking changes in its core dependency, `vfile`. Key differentiators include its tight integration with the vfile specification, extensive configuration options for output customization (e.g., color, verbosity, quiet/silent modes), and its role as a standard reporting mechanism for unified (remark, rehype, etc.) processors.","status":"active","version":"8.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/vfile/vfile-reporter","tags":["javascript","vfile","vfile-util","vfile-reporter","util","utility","reporter","virtual","file","typescript"],"install":[{"cmd":"npm install vfile-reporter","lang":"bash","label":"npm"},{"cmd":"yarn add vfile-reporter","lang":"bash","label":"yarn"},{"cmd":"pnpm add vfile-reporter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for creating and managing virtual files with messages.","package":"vfile","optional":false}],"imports":[{"note":"Since v7.0.0, `vfile-reporter` is an ESM-only package. CommonJS `require` is not supported. The `reporter` function is a named export.","wrong":"const { reporter } = require('vfile-reporter')","symbol":"reporter","correct":"import { reporter } from 'vfile-reporter'"},{"note":"The `reporter` function is also provided as the default export for convenience.","symbol":"reporter","correct":"import reporter from 'vfile-reporter'"},{"note":"For TypeScript users, the `Options` interface can be imported as a type for configuring the reporter's behavior.","symbol":"Options","correct":"import type { Options } from 'vfile-reporter'"}],"quickstart":{"code":"import { VFile } from 'vfile';\nimport { reporter } from 'vfile-reporter';\n\n// Create some VFile instances\nconst fileOne = new VFile({\n  path: 'src/module-a.js',\n  value: 'console.log(\\\"Hello\\\")'\n});\nconst fileTwo = new VFile({\n  path: 'src/module-b.js',\n  value: 'const x = 1;'\n});\n\n// Add messages to fileOne\nfileOne.message('This is a warning!', { line: 1, column: 9 }, 'linter:warning-id');\nfileOne.message('Another issue at line 2.', 2);\n\n// Use the reporter to generate a report for both files\n// console.error is often used for reports to stderr\nconst report = reporter([fileOne, fileTwo], { verbose: true });\nconsole.error(report);\n\n/* Expected output (may vary slightly based on environment):\nsrc/module-a.js\n  1:9  warning  This is a warning!  linter:warning-id\n  2:1  warning  Another issue at line 2.\n\nsrc/module-b.js: no issues found\n\n⚠ 2 warnings\n*/","lang":"typescript","description":"Demonstrates creating multiple VFiles, adding messages to them, and then generating a formatted, human-readable report using `vfile-reporter` with verbose options."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher. `nvm install 16 && nvm use 16`.","message":"Version 8.0.0 of `vfile-reporter` dropped support for Node.js versions older than 16. Running on earlier Node.js versions will result in runtime errors.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Convert your module to ES Modules (using `import` statements and setting `type: 'module'` in `package.json`) or use dynamic `import()` within CommonJS.","message":"Since version 7.0.0, `vfile-reporter` is an ESM-only package. Attempting to `require()` it in a CommonJS module will throw an `ERR_REQUIRE_ESM` error.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Implement explicit error handling and ensure that only valid `VFile` instances are passed to the `reporter` function. Filter out nullish or errored files beforehand.","message":"Version 8.0.0 removed direct support for 'errors' and 'nullish files'. Previously, the reporter might have handled these implicitly. Users are now expected to handle such conditions explicitly before passing files to the reporter.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Ensure you are only importing and using the publicly documented API, such as the `reporter` function from the top-level package export. Avoid relying on internal module paths.","message":"Version 8.0.0 changed to use an `export` map, which means private internal APIs (e.g., direct deep imports) are no longer accessible and will break. The package intends for only its public API to be used.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Review `vfile@5.0.0` changelog for breaking changes and update your `vfile` usage accordingly in your codebase.","message":"Version 7.0.0 updated its dependency on `vfile` to `v5.0.0`. If your project also uses `vfile` directly, ensure compatibility with `vfile@5.0.0` as it may contain its own breaking changes.","severity":"breaking","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `import { reporter } from 'vfile-reporter'` in an ES Module context. Ensure your `package.json` has `\"type\": \"module\"` or your file ends with `.mjs`.","cause":"`vfile-reporter` is an ES Module and cannot be loaded with CommonJS `require()`.","error":"ERR_REQUIRE_ESM: require() of ES Module .../node_modules/vfile-reporter/index.js from ... not supported."},{"fix":"Always pass valid `VFile` objects. Ensure `vfile` is correctly imported and instantiated: `import { VFile } from 'vfile'; new VFile(...)`.","cause":"The `reporter` function expects an array of `VFile` instances or a single `VFile` instance.","error":"TypeError: Cannot read properties of undefined (reading 'message') or similar when `files` is not a `VFile` instance."},{"fix":"Ensure `vfile` is installed as a dependency: `npm install vfile`.","cause":"`vfile`, a core dependency of `vfile-reporter`, is not installed or resolved correctly.","error":"Error: Cannot find module 'vfile' or similar dependency error."},{"fix":"Ensure you are using `vfile-reporter` v7.0.1 or later for named exports. Try `import reporter from 'vfile-reporter'` if you suspect it's a default-only export issue or check your build configuration.","cause":"This error might occur if you are trying to use a named import (e.g., `{ reporter }`) on an older version that only supported default exports, or if your bundler configuration is incorrect.","error":"SyntaxError: Named export 'reporter' not found. The requested module 'vfile-reporter' does not provide an export named 'reporter'"}],"ecosystem":"npm"}