Project: vfile/vfile

Package: vfile@5.2.0

  1. Dependents: 192
  2. Virtual file format for text processing
  1. remark 187
  2. rehype 87
  3. retext 37
  4. file 34
  5. virtual 19
  6. text 19
  7. vfile 17
  8. message 8
  9. processing 3
  10. warning 3
  11. error 3


Build Coverage Downloads Size Sponsors Backers Chat

vfile is a small and browser friendly virtual file format that tracks metadata (such as a file’s path and value) and messages.

It was made specifically for unified and generally for the common task of parsing, transforming, and serializing data, where vfile handles everything about the document being compiled. This is useful for example when building linters, compilers, static site generators, or other build tools. vfile is part of the unified collective.

vfile is different from the excellent vinyl in that it has a smaller API, a smaller size, and focuses on messages.



This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.


npm install vfile


import {VFile} from 'vfile'

var file = new VFile({path: '~/example.txt', value: 'Alpha *braavo* charlie.'})

file.path // => '~/example.txt'
file.dirname // => '~'

file.extname = '.md'

file.basename // => 'example.md'

file.basename = 'index.text'

file.history // => ['~/example.txt', '~/example.md', '~/index.text']

file.message('`braavo` is misspelt; did you mean `bravo`?', {line: 1, column: 8})



  [~/index.text:1:8: `braavo` is misspelt; did you mean `bravo`?] {
    reason: '`braavo` is misspelt; did you mean `bravo`?',
    line: 1,
    column: 8,
    source: null,
    ruleId: null,
    position: {start: [Object], end: [Object]},
    file: '~/index.text',
    fatal: false


This package exports the following identifiers: VFile. There is no default export.


Create a new virtual file. If options is string or Buffer, treats it as {value: options}. If options is a VFile, shallow copies its data over to the new file. All other given fields are set on the newly created VFile.

Path related properties are set in the following order (least specific to most specific): history, path, basename, stem, extname, dirname.

It’s not possible to set either dirname or extname without setting either history, path, basename, or stem as well.

new VFile()
new VFile('console.log("alpha");')
new VFile(Buffer.from('exit 1'))
new VFile({path: path.join('path', 'to', 'readme.md')})
new VFile({stem: 'readme', extname: '.md', dirname: path.join('path', 'to')})
new VFile({other: 'properties', are: 'copied', ov: {e: 'r'}})


Buffer, string, null — Raw value.


string — Base of path. Defaults to process.cwd().


string? — Path of vfile. Cannot be nullified. You can set a file URL (a URL object with a file: protocol) which will be turned into a path with url.fileURLToPath.


string? — Current name (including extension) of vfile. Cannot contain path separators. Cannot be nullified either (use file.path = file.dirname instead).


string? — Name (without extension) of vfile. Cannot be nullified, and cannot contain path separators.


string? — Extension (with dot) of vfile. Cannot be set if there’s no path yet and cannot contain path separators.


string? — Path to parent directory of vfile. Cannot be set if there’s no path yet.


Array.<string> — List of file-paths the file moved between.


Array.<VMessage> — List of messages associated with the file.


Object — Place to store custom information. It’s OK to store custom data directly on the vfile, moving it to data gives a little more privacy.


Convert value of vfile to string. When value is a Buffer, encoding is a character encoding to understand it as (string, default: 'utf8').

VFile#message(reason[, position][, origin])

Associates a message with the file, where fatal is set to false. Constructs a new VMessage and adds it to vfile.messages.



VFile#info(reason[, position][, origin])

Associates an informational message with the file, where fatal is set to null. Calls #message() internally.



VFile#fail(reason[, position][, origin])

Associates a fatal message with the file, then immediately throws it. Note: fatal errors mean a file is no longer processable. Calls #message() internally.



List of utilities

The following list of projects includes tools for working with virtual files. See unist for projects that work with nodes.


The following list of projects show linting results for given virtual files. Reporters must accept Array.<VFile> as their first argument, and return string. Reporters may accept other values too, in which case it’s suggested to stick to vfile-reporters interface.


See contributing.md in vfile/.github for ways to get started. See support.md for ways to get help. Ideas for new utilities and tools can be posted in vfile/ideas.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

Support this effort and give back by sponsoring on OpenCollective!

Gatsby 🥇

Vercel 🥇




Boost Hub




The initial release of this project was authored by @wooorm.

Thanks to @contra, @phated, and others for their work on Vinyl, which was a huge inspiration.

Thanks to @brendo, @shinnn, @KyleAMathews, @sindresorhus, and @denysdovhan for contributing commits since!


MIT © Titus Wormer