JS-YAML is a high-performance JavaScript library for parsing and serializing YAML 1.2 documents. Originally inspired by PyYAML, it underwent a complete rewrite to optimize for speed and full adherence to the latest YAML specification. The current stable version, 4.1.1, offers robust functionalities including both 'safe' and 'full' modes for loading and dumping YAML data, catering to various security and feature requirements. It maintains a regular release cadence for bug fixes and minor improvements, with major versions introducing significant API or feature changes. Key differentiators include its speed, comprehensive support for YAML 1.2 tags, and a strong emphasis on providing a secure parsing option via `safeLoad`, which limits potentially unsafe features like arbitrary code execution. While primarily used in Node.js, it also provides a browser-compatible build, though its browser support is explicitly noted as less thoroughly tested and may require additional shims for older environments.
npm install js-yamlVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to load YAML from a file using `safeLoad` and serialize a JavaScript object to YAML using `safeDump`, emphasizing safe practices.
Prior to v4.0.0, duplicate keys in YAML mappings might have silently overwritten values or had undefined behavior. From v4.0.0, parsing YAML with duplicate keys will throw a `YAMLException`. To replicate `JSON.parse` behavior where the last key overrides previous ones, set the `json: true` option in `safeLoad` or `load`: `yaml.safeLoad(data, { json: true })`.Always prefer `yaml.safeLoad()` for parsing YAML from untrusted or external sources to prevent arbitrary code execution via dangerous JavaScript-specific tags (e.g., `!!js/function`, `!!js/regexp`). Similarly, use `yaml.safeDump()` for generating standard YAML output.
The browser bundle is not extensively tested by maintainers. Be aware that `!!js/function` requires `esprima` to be loaded separately, and `!!bin` tags will return JavaScript `Array` instances instead of Node.js `Buffer` objects. Older browsers may require `es5-shims`.
If you intend to parse `!!js/function` tags in a browser environment, you must explicitly load the `esprima.js` parser before `js-yaml.min.js`. This functionality is generally discouraged for security reasons with untrusted input, as it allows arbitrary code execution.
Carefully review the YAML content, specifically around the indicated line and column, for consistent spacing and proper nesting. YAML uses spaces, not tabs, for indentation.
Ensure the package is installed by running `npm install js-yaml` or `yarn add js-yaml`. Verify that the import statement correctly references the package name, e.g., `const yaml = require('js-yaml');` or `import { safeLoad } from 'js-yaml';`.Implement defensive programming by checking for `null` or `undefined` values before accessing properties, especially for optional YAML fields. Use optional chaining (`?.`) or nullish coalescing (`??`) if your environment supports it.