{"id":12696,"library":"yaml","title":"YAML Parser and Stringifier","description":"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).","status":"active","version":"2.8.3","language":"javascript","source_language":"en","source_url":"https://github.com/eemeli/yaml","tags":["javascript","YAML","parser","stringifier","typescript"],"install":[{"cmd":"npm install yaml","lang":"bash","label":"npm"},{"cmd":"yarn add yaml","lang":"bash","label":"yarn"},{"cmd":"pnpm add yaml","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Use named import for parsing YAML strings into JavaScript objects or YAML Documents.","wrong":"const parse = require('yaml').parse","symbol":"parse","correct":"import { parse } from 'yaml'"},{"note":"Use named import for converting JavaScript objects or YAML Documents back into YAML strings.","wrong":"const stringify = require('yaml').stringify","symbol":"stringify","correct":"import { stringify } from 'yaml'"},{"note":"The `Document` class represents a single YAML document within a stream, allowing for advanced AST manipulation and meta-data access.","wrong":"const Document = require('yaml').Document","symbol":"Document","correct":"import { Document } from 'yaml'"},{"note":"For parsing a single YAML document and returning a `Document` instance, which provides richer API access than `parse`.","wrong":"const parseDocument = require('yaml').parseDocument","symbol":"parseDocument","correct":"import { parseDocument } from 'yaml'"},{"note":"These classes represent core YAML AST nodes (mappings, sequences, scalars) and are used for low-level document manipulation.","wrong":"const { YAMLMap } = require('yaml')","symbol":"YAMLMap, YAMLSeq, Scalar","correct":"import { YAMLMap, YAMLSeq, Scalar } from 'yaml'"}],"quickstart":{"code":"import { parse, stringify, Document, YAMLMap, Scalar } from 'yaml';\n\nconst yamlString = `\n# My shopping list\n- item: Apples\n  quantity: 2\n  notes: Green ones\n\n---\n# My second shopping list\n- item: Milk\n  quantity: 1\n  unit: gallon\n`;\n\n// Parse a multi-document YAML string, keeping CST nodes for better comment preservation\nconst documents = parse(yamlString, { keepCstNodes: true }) as Document[];\n\n// Access and modify the first document\nconst firstDoc = documents[0];\nif (firstDoc && firstDoc.contents instanceof Array) { // Assuming a sequence at root\n  const appleItem = firstDoc.contents[0];\n  if (appleItem instanceof YAMLMap) {\n    appleItem.set('quantity', 3); // Change quantity\n    appleItem.set('notes', 'Honeycrisp preferred'); // Update notes\n  }\n}\n\n// Access and modify the second document\nconst secondDoc = documents[1];\nif (secondDoc && secondDoc.contents instanceof Array) {\n  secondDoc.contents.push(new YAMLMap());\n  const newItem = secondDoc.contents[secondDoc.contents.length - 1] as YAMLMap;\n  newItem.set('item', 'Bread');\n  newItem.set('quantity', 1);\n  newItem.set('type', 'whole wheat');\n}\n\n// Stringify the modified documents back to YAML\nconst modifiedYaml = documents.map(doc => stringify(doc)).join('\\n---\\n');\n\nconsole.log('Original YAML:\\n', yamlString);\nconsole.log('\\nModified YAML:\\n', modifiedYaml);\n\n// Example of parsing a single document with parseDocument and accessing AST\nconst singleDocString = `\nuser: John Doe\nroles:\n  - admin\n  - editor\nactive: true\n`;\n\nconst doc = parseDocument(singleDocString);\n\nif (doc.contents instanceof YAMLMap) {\n  const userNode = doc.contents.get('user');\n  if (userNode instanceof Scalar) {\n    console.log(`\\nUser from single document: ${userNode.value}`);\n  }\n  doc.contents.set('status', 'online');\n}\n\nconsole.log('\\nModified Single Document with new status:\\n', doc.toString());\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0-0"},{"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.","message":"Node.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.","severity":"breaking","affected_versions":">=2.7.0 <2.8.0"},{"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).","message":"The minimum supported TypeScript version for the included typings is 3.9. Using the library with earlier TypeScript versions may result in type errors.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"While 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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update imports to use ESM syntax: `import { parse, stringify } from 'yaml'`.","cause":"Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment (e.g., `\"type\": \"module\"` in `package.json` or `.mjs` files).","error":"ReferenceError: require is not defined"},{"fix":"Ensure you are using named imports: `import { parse, stringify } from 'yaml'`.","cause":"Incorrectly importing named exports, often by trying to use a default import or a CommonJS-style property access with ESM.","error":"Property 'parse' does not exist on type 'typeof import(\"yaml\")' or 'yaml.parse is not a function'"},{"fix":"Update your Node.js environment to a version `>= 14.6` or higher to meet the package's engine requirements.","cause":"Running the library on an unsupported Node.js version.","error":"Error: The current Node.js version is <some-version> which does not satisfy the requirement >= 14.6."}],"ecosystem":"npm"}