vfile-matter

library5.0.1jsnpmunverified

vfile-matter is a utility package for the vfile ecosystem, designed to parse YAML front matter found at the beginning of a virtual file. It's currently stable at version 5.0.1, with minor updates and patch releases occurring as needed, and major versions released periodically to align with ecosystem updates and Node.js LTS cycles. This package populates the parsed data into `file.data.matter` and can optionally strip the front matter content from the file's `value`. A key differentiator is its tight integration with `vfile`, making it suitable for direct file manipulation when not using a higher-level parsing system like remark. Since version 4.0.0, it uses the more modern `yaml` package for parsing, replacing `js-yaml`. It's important to note that this package is distinct from `remark-frontmatter`, which should be used when processing Markdown with `remark` rather than directly manipulating `vfile` objects.

serialization workflow

npm install vfile-matter

github ↗package ↗

INSTALL

IMPORT

SIG · VFILE-MATTER

vfile-matter

serializationjavascriptv5.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

matter

✓ import { matter } from 'vfile-matter'

✗ const matter = require('vfile-matter')

vfile-matter has been ESM-only since v3.0.0. CommonJS `require` will result in an `ERR_REQUIRE_ESM` error.

Options

✓ import type { Options } from 'vfile-matter'

✗ import { Options } from 'vfile-matter'

This is a TypeScript type, not a runtime value. Use `import type`.

YamlOptions

✓ import type { YamlOptions } from 'vfile-matter'

✗ import { YamlOptions } from 'vfile-matter'

This is a TypeScript type, not a runtime value. Use `import type`.

Demonstrates parsing YAML front matter from a virtual file and stripping it from the content using `vfile-matter`.

import { read } from 'to-vfile'; import { matter } from 'vfile-matter'; const exampleFileContent = `---\nlayout: solar-system\ntitle: Jupiter\n---\n<h1>Jupiter</h1>\n`; async function processFile() { // In a real scenario, you'd read from a file path // For this example, we create a VFile directly const file = await read({ path: 'example.html', value: exampleFileContent }); // Parse the YAML front matter and optionally strip it matter(file, { strip: true }); console.log('Parsed Matter:', file.data.matter); console.log('File Content (after stripping):', String(file)); } processFile().catch(console.error); /* To run this example, ensure you have 'vfile-matter' and 'to-vfile' installed: npm install vfile-matter to-vfile */

Debug

Known issues

breakingvfile-matter v5.0.0 and above require Node.js 16 or higher. Running on older Node.js versions will result in errors.

fix

Upgrade your Node.js environment to version 16 or newer.

affects: >=5.0.0

breakingSince v5.0.0, the `matter` function no longer returns the `VFile` object, but instead returns `undefined`. Operations are performed directly on the `file` object passed as an argument.

fix

Access the modified file directly from the variable you passed to `matter`, e.g., `const file = await read(...); matter(file); console.log(file.data.matter);`

affects: >=5.0.0

breakingvfile-matter switched to ESM-only in v3.0.0. CommonJS `require()` statements will fail with `ERR_REQUIRE_ESM`.

fix

Migrate your project to use ECMAScript Modules (`import`/`export`) or stick to `vfile-matter@2.x` if CJS is strictly required.

affects: >=3.0.0

breakingvfile-matter v4.0.0 replaced the `js-yaml` parser with the `yaml` package. While largely API compatible, specific options or behaviors tied to `js-yaml` might change.

fix

Review `YamlOptions` for any parser-specific configurations if you encounter unexpected behavior after upgrading from v3.x.

affects: >=4.0.0

gotchaIf you are processing Markdown files with `remark`, it is generally recommended to use `remark-frontmatter` instead of `vfile-matter`. `remark-frontmatter` integrates directly into the AST processing, preserving positional information correctly.

fix

For `remark` pipelines, use `import remarkFrontmatter from 'remark-frontmatter'` and add it to your `unified().use(...)` chain.

affects: >=3.0.0

gotchaUsing the `strip: true` option to remove front matter from the file's content can alter positional information. This can cause issues with other tools or plugins that rely on accurate character offsets for warnings, errors, or source map generation.

fix

Only use `strip: true` if you are certain no downstream processes depend on the original positional information. Otherwise, manage the content without stripping the front matter.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to `require()` vfile-matter in a CommonJS module, but it is an ESM-only package since v3.0.0.

fix

Change `const { matter } = require('vfile-matter')` to `import { matter } from 'vfile-matter'` and ensure your project uses ES modules (e.g., `"type": "module"` in package.json or `.mjs` file extension).

TypeError: matter is not a function

Incorrect import statement (e.g., `import matter from 'vfile-matter'` instead of named import) or calling `matter` on an undefined/null value.

fix

Ensure you are using a named import: `import { matter } from 'vfile-matter'`. Also verify that the `file` object passed to `matter` is a valid `VFile` instance.

Cannot find module 'vfile-matter'

The package is not installed, or Node.js version is incompatible with the `exports` map defined in `package.json` (since v5.0.0), or there's a problem with module resolution.

fix

First, ensure `npm install vfile-matter` is run. If it persists, check your Node.js version (must be 16+ for v5.0.0+). If using specific module resolution tools, check their configuration.

Upgrade

Version history

5.0.1latest on npm

Audit

Dependencies

vfilerequiredCore dependency for virtual file manipulation; operates on VFile objects.

yamlrequiredRuntime dependency for parsing YAML front matter; replaced `js-yaml` in v4.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vfile/vfile-matter ↗

packagehttps://www.npmjs.com/package/vfile-matter ↗