Announcing the unified collective! 🎉 Read more about it on Medium »
vfile is a virtual file format used by unified, a text processing umbrella (it powers retext for natural language, remark for markdown, and rehype for HTML). Each processors that parse, transform, and compile text, and need a virtual representation of files and a place to store messages about them. Plus, they work in the browser. vfile provides these requirements at a small size.
unified.js.organd try its guides for an overview
- Read unified’s readme for a technical intro
- Follow us on Medium and Twitter to see what we’re up to
- Check out Contribute below to find out how to help out
vfile can be used anywhere where files need a lightweight representation. For example, it’s used in:
awoo— Declarative small site generator
geojsonhint— Complete, fast, standards-based validation for geojson
npm install vfile
Table of Contents
var vfile =var file =filepath // => '~/example.txt'filedirname // => '~'fileextname = '.md'filebasename // => 'example.md'filebasename = 'index.text'filehistory // => ['~/example.txt', '~/example.md', '~/index.text']fileconsole
~/indextext:1:8: `braavo` is misspelt; did you mean `bravo`?message: '`braavo` is misspelt; did you mean `bravo`?'name: '~/index.text:1:8'file: '~/index.text'reason: '`braavo` is misspelt; did you mean `bravo`?'line: 1column: 8location: start: Object end: ObjectruleId: nullsource: nullfatal: false
The following list of projects includes tools for working with virtual files. See unist for projects working with nodes.
convert-vinyl-to-vfile— Convert from Vinyl
is-vfile-message— Check if a value is a
to-vfile— Create a virtual file from a file-path (and optionally read it)
vfile-find-down— Find files by searching the file system downwards
vfile-find-up— Find files by searching the file system upwards
vfile-glob— Find files by glob patterns
vfile-is— Check if a file passes a test
vfile-location— Convert between line/column- and range-based locations
vfile-message— Create a
VMessageobject (used in
vfile-messages-to-vscode-diagnostics— Convert to VS Code diagnostics
vfile-statistics— Count messages per category
vfile-sort— Sort messages by line/column
vfile-to-eslint— Convert vfiles to ESLint formatter compatible output
The following list of projects show linting results for given virtual files.
Reporters must accept
Array.<VFile> as their first argument, and return
Reporters may accept other values too, in which case it’s suggested to stick
vfile-reporter— Stylish reporter
vfile-reporter-json— JSON reporter
vfile-reporter-folder-json— JSON reporter with a folder structure
vfile-reporter-pretty— Pretty reporter
Create a new virtual file.
Buffer, treats it as
options is a
VFile, returns it.
All other options are set on the newly created
Path related properties are set in the following order (least specific
to most specific):
It’s not possible to set either
extname without setting
stem as well.
null — Raw value.
string — Base of
string? — Path of
Cannot be nullified.
string? — Current name (including extension) of
Cannot contain path separators.
Cannot be nullified either (use
file.path = file.dirname instead).
string? — Name (without extension) of
Cannot be nullified, and cannot contain path separators.
string? — Extension (with dot) of
Cannot be set if there’s no
path yet and cannot contain path separators.
string? — Path to parent directory of
Cannot be set if there’s no
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
a little more privacy.
Convert contents of
vfile to string.
contents is a buffer,
encoding is used to stringify buffers (default:
VFile#message(reason[, position][, origin])
VFile#info(reason[, position][, origin])
Associates an informational message with the file, where
fatal is set to
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.
vfile is built by people just like you!
contributing.md for ways to get started.
This project has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.
Want to chat with the community and contributors? Join us in spectrum!
Have an idea for a cool new utility or tool?
If you want feedback, help, or just to share it with the world you can do so by
creating an issue in the
The initial release of this project was authored by @wooorm.