Registry / serialization / yaml
library2.8.3jsnpmunverified

The `yaml` library is a robust and definitive JavaScript parser and stringifier for YAML, supporting both YAML 1.1 and 1.2 specifications and all common data schemas. It currently maintains a stable version 2.8.3, with an active release cadence that regularly introduces new features and bug fixes. A v3.0.0-0 prerelease is also available under the `next` tag, though it is not yet stable for production use and is not recommended for production environments. Key differentiators include passing all `yaml-test-suite` tests, its ability to parse any string input without throwing errors (extracting as much YAML as possible), and comprehensive support for parsing, modifying, and writing YAML comments and blank lines. It boasts no external dependencies and runs across various JavaScript environments including Node.js (requiring `>= 14.6`), modern browsers, Deno, Bun, and Cloudflare Workers, shipping with full TypeScript type definitions (minimum TS 3.9).

npm install yaml
INSTALL
IMPORT
SIG · YAML
Y
yaml
serializationjavascriptv2.8.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

parse
import { parse } from 'yaml'
const parse = require('yaml').parse
Use named import for parsing YAML strings into JavaScript objects or YAML Documents.
stringify
import { stringify } from 'yaml'
const stringify = require('yaml').stringify
Use named import for converting JavaScript objects or YAML Documents back into YAML strings.
Document
import { Document } from 'yaml'
const Document = require('yaml').Document
The `Document` class represents a single YAML document within a stream, allowing for advanced AST manipulation and meta-data access.
parseDocument
import { parseDocument } from 'yaml'
const parseDocument = require('yaml').parseDocument
For parsing a single YAML document and returning a `Document` instance, which provides richer API access than `parse`.
YAMLMap, YAMLSeq, Scalar
import { YAMLMap, YAMLSeq, Scalar } from 'yaml'
const { YAMLMap } = require('yaml')
These classes represent core YAML AST nodes (mappings, sequences, scalars) and are used for low-level document manipulation.

This quickstart demonstrates parsing multi-document YAML strings, modifying values and adding new items using the Document API, and then stringifying the result. It also shows parsing a single document with `parseDocument` and direct AST manipulation.

import { parse, stringify, Document, YAMLMap, Scalar } from 'yaml'; const yamlString = ` # My shopping list - item: Apples quantity: 2 notes: Green ones --- # My second shopping list - item: Milk quantity: 1 unit: gallon `; // Parse a multi-document YAML string, keeping CST nodes for better comment preservation const documents = parse(yamlString, { keepCstNodes: true }) as Document[]; // Access and modify the first document const firstDoc = documents[0]; if (firstDoc && firstDoc.contents instanceof Array) { // Assuming a sequence at root const appleItem = firstDoc.contents[0]; if (appleItem instanceof YAMLMap) { appleItem.set('quantity', 3); // Change quantity appleItem.set('notes', 'Honeycrisp preferred'); // Update notes } } // Access and modify the second document const secondDoc = documents[1]; if (secondDoc && secondDoc.contents instanceof Array) { secondDoc.contents.push(new YAMLMap()); const newItem = secondDoc.contents[secondDoc.contents.length - 1] as YAMLMap; newItem.set('item', 'Bread'); newItem.set('quantity', 1); newItem.set('type', 'whole wheat'); } // Stringify the modified documents back to YAML const modifiedYaml = documents.map(doc => stringify(doc)).join('\n---\n'); console.log('Original YAML:\n', yamlString); console.log('\nModified YAML:\n', modifiedYaml); // Example of parsing a single document with parseDocument and accessing AST const singleDocString = ` user: John Doe roles: - admin - editor active: true `; const doc = parseDocument(singleDocString); if (doc.contents instanceof YAMLMap) { const userNode = doc.contents.get('user'); if (userNode instanceof Scalar) { console.log(`\nUser from single document: ${userNode.value}`); } doc.contents.set('status', 'online'); } console.log('\nModified Single Document with new status:\n', doc.toString());
Debug
Known issues
breakingVersion 3.0.0-0 is a prerelease and highly unstable. It's published under the `next` dist-tag and using a non-exact range like `^3.0.0-0` can cause unpredictable breaking changes when new prereleases are published.
fix
For v3 prereleases, always install with `npm install --save-exact yaml@next` to pin to a specific unstable version, or avoid using it in production until the final release.
affects: >=3.0.0-0
breakingNode.js engine requirement shifted in `v2.7.0` to `>= 14.18` from `>= 14.6`, then reverted to `>= 14.6` in `v2.8.0`. Ensure your Node.js environment meets the specific requirement for the minor version of `yaml` you are using to avoid runtime errors.
fix
Check the `engines.node` field in `package.json` for your specific `yaml` version or update Node.js to a version `>= 14.18` for broader compatibility within the v2 range.
affects: >=2.7.0 <2.8.0
gotchaThe minimum supported TypeScript version for the included typings is 3.9. Using the library with earlier TypeScript versions may result in type errors.
fix
Update your TypeScript compiler to version 3.9 or newer, or set `skipLibCheck: true` in your `tsconfig.json` to bypass type checking for declaration files (use with caution).
affects: >=2.0.0
gotchaWhile documented endpoints are semver-major, undocumented library internals may change between minor versions. Relying on internal structures not explicitly part of the public API can lead to unexpected breakages.
fix
Adhere strictly to the documented API endpoints and classes. Avoid directly accessing private properties or methods which may be subject to change without a major version bump.
affects: >=2.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment (e.g., `"type": "module"` in `package.json` or `.mjs` files).
fix
Update imports to use ESM syntax: `import { parse, stringify } from 'yaml'`.
Property 'parse' does not exist on type 'typeof import("yaml")' or 'yaml.parse is not a function'
Incorrectly importing named exports, often by trying to use a default import or a CommonJS-style property access with ESM.
fix
Ensure you are using named imports: `import { parse, stringify } from 'yaml'`.
Error: The current Node.js version is <some-version> which does not satisfy the requirement >= 14.6.
Running the library on an unsupported Node.js version.
fix
Update your Node.js environment to a version `>= 14.6` or higher to meet the package's engine requirements.
Upgrade
Version history
2.8.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
8
Amazon
1
Resources