{"id":12357,"library":"vfile-matter","title":"vfile-matter","description":"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.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/vfile/vfile-matter","tags":["javascript","file","frontmatter","matter","utility","util","vfile-util","vfile","virtual","typescript"],"install":[{"cmd":"npm install vfile-matter","lang":"bash","label":"npm"},{"cmd":"yarn add vfile-matter","lang":"bash","label":"yarn"},{"cmd":"pnpm add vfile-matter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for virtual file manipulation; operates on VFile objects.","package":"vfile","optional":false},{"reason":"Runtime dependency for parsing YAML front matter; replaced `js-yaml` in v4.","package":"yaml","optional":false}],"imports":[{"note":"vfile-matter has been ESM-only since v3.0.0. CommonJS `require` will result in an `ERR_REQUIRE_ESM` error.","wrong":"const matter = require('vfile-matter')","symbol":"matter","correct":"import { matter } from 'vfile-matter'"},{"note":"This is a TypeScript type, not a runtime value. Use `import type`.","wrong":"import { Options } from 'vfile-matter'","symbol":"Options","correct":"import type { Options } from 'vfile-matter'"},{"note":"This is a TypeScript type, not a runtime value. Use `import type`.","wrong":"import { YamlOptions } from 'vfile-matter'","symbol":"YamlOptions","correct":"import type { YamlOptions } from 'vfile-matter'"}],"quickstart":{"code":"import { read } from 'to-vfile';\nimport { matter } from 'vfile-matter';\n\nconst exampleFileContent = `---\\nlayout: solar-system\\ntitle: Jupiter\\n---\\n<h1>Jupiter</h1>\\n`;\n\nasync function processFile() {\n  // In a real scenario, you'd read from a file path\n  // For this example, we create a VFile directly\n  const file = await read({ path: 'example.html', value: exampleFileContent });\n\n  // Parse the YAML front matter and optionally strip it\n  matter(file, { strip: true });\n\n  console.log('Parsed Matter:', file.data.matter);\n  console.log('File Content (after stripping):', String(file));\n}\n\nprocessFile().catch(console.error);\n\n/*\nTo run this example, ensure you have 'vfile-matter' and 'to-vfile' installed:\nnpm install vfile-matter to-vfile\n*/","lang":"typescript","description":"Demonstrates parsing YAML front matter from a virtual file and stripping it from the content using `vfile-matter`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer.","message":"vfile-matter v5.0.0 and above require Node.js 16 or higher. Running on older Node.js versions will result in errors.","severity":"breaking","affected_versions":">=5.0.0"},{"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);`","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Migrate your project to use ECMAScript Modules (`import`/`export`) or stick to `vfile-matter@2.x` if CJS is strictly required.","message":"vfile-matter switched to ESM-only in v3.0.0. CommonJS `require()` statements will fail with `ERR_REQUIRE_ESM`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review `YamlOptions` for any parser-specific configurations if you encounter unexpected behavior after upgrading from v3.x.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"For `remark` pipelines, use `import remarkFrontmatter from 'remark-frontmatter'` and add it to your `unified().use(...)` chain.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to `require()` vfile-matter in a CommonJS module, but it is an ESM-only package since v3.0.0.","error":"ERR_REQUIRE_ESM"},{"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.","cause":"Incorrect import statement (e.g., `import matter from 'vfile-matter'` instead of named import) or calling `matter` on an undefined/null value.","error":"TypeError: matter is not a function"},{"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.","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.","error":"Cannot find module 'vfile-matter'"}],"ecosystem":"npm"}