vfile-matter

5.0.1 · active · verified Sun Apr 19

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.

Common errors

```
ERR_REQUIRE_ESM
```
cause 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
```
cause 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'
```
cause 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.

Warnings

breaking vfile-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.
breaking Since 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);`
breaking vfile-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.
breaking vfile-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.
gotcha If 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.
gotcha Using 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.

Install

npm install vfile-matter npm
yarn add vfile-matter yarn
pnpm add vfile-matter pnpm

Imports

matter
wrong:
```
const matter = require('vfile-matter')
```
correct:
```
import { matter } from 'vfile-matter'
```
vfile-matter has been ESM-only since v3.0.0. CommonJS `require` will result in an `ERR_REQUIRE_ESM` error.
Options
wrong:
```
import { Options } from 'vfile-matter'
```
correct:
```
import type { Options } from 'vfile-matter'
```
This is a TypeScript type, not a runtime value. Use `import type`.
YamlOptions
wrong:
```
import { YamlOptions } from 'vfile-matter'
```
correct:
```
import type { YamlOptions } from 'vfile-matter'
```
This is a TypeScript type, not a runtime value. Use `import type`.

Quickstart

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
*/

view raw JSON →