This package provides a virtual file format.
It exposes an API to access the file value, path, metadata about the file, and
specifically supports attaching lint messages and errors to certain places in
these files.
When should I use this?
The virtual file format is useful when dealing with the concept of files in
places where you might not be able to access the file system.
The message API is particularly useful when making things that check files (as
in, linting).
vfile is made for unified, which amongst other things checks files.
However, vfile can be used in other projects that deal with parsing,
transforming, and serializing data, to build linters, compilers, static site
generators, and other build tools.
This is different from the excellent vinyl in that vfile has a
smaller API, a smaller size, and focuses on messages.
Install
This package is ESM only.
In Node.js (version 16+), install with npm:
Get or set the basename (including extname) (string?, example: 'index.min.js').
Cannot contain path separators ('/' on unix, macOS, and browsers, '\' on
windows).
Cannot be nullified (use file.path = file.dirname instead).
file.dirname
Get or set the parent path (string?, example: '~').
Cannot be set if there’s no path yet.
file.extname
Get or set the extname (including dot) (string?, example: '.js').
Cannot contain path separators ('/' on unix, macOS, and browsers, '\' on
windows).
Cannot be set if there’s no path yet.
file.path
Get or set the full path (string?, example: '~/index.min.js').
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.
file.stem
Get or set the stem (basename w/o extname) (string?, example: 'index.min').
Cannot contain path separators ('/' on unix, macOS, and browsers, '\' on
windows).
Cannot be nullified.
VFile#fail(reason[, options])
Create a fatal message for reason associated with the file.
The fatal field of the message is set to true (error; file not usable) and
the file field is set to the current file path.
The message is added to the messages field on file.
🪦 Note: also has obsolete signatures.
Parameters
reason (string)
— reason for message, should use markdown
Create an info message for reason associated with the file.
The fatal field of the message is set to undefined (info; change likely not
needed) and the file field is set to the current file path.
The message is added to the messages field on file.
🪦 Note: also has obsolete signatures.
Parameters
reason (string)
— reason for message, should use markdown
Create a message for reason associated with the file.
The fatal field of the message is set to false (warning; change may be
needed) and the file field is set to the current file path.
The message is added to the messages field on file.
🪦 Note: also has obsolete signatures.
Parameters
reason (string)
— reason for message, should use markdown
The following fields are considered “non-standard”, but they are allowed, and
some utilities use them:
map (Map)
— source map; this type is equivalent to the RawSourceMap type from the
source-map module
result (unknown)
— custom, non-string, compiled, representation; this is used by unified to
store non-string results; one example is when turning markdown into React
nodes
stored (boolean)
— whether a file was saved to disk; this is used by vfile reporters
👉 Note: want to make your own reporter?
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.
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, vfile@^6,
compatible with Node.js 16.