js-yaml: The JavaScript YAML Parser and Serializer Built for Spec Compliance

What js-yaml Solves and Who Uses It

Modern JavaScript projects routinely read YAML files for configuration: CI/CD pipeline definitions, Docker Compose files, Kubernetes manifests, and application settings all ship as YAML. The Node.js runtime has no built-in YAML parser, so projects must reach for a library. js-yaml fills that gap. It is a pure JavaScript implementation, meaning it works in any environment that runs JavaScript, including browsers, edge runtimes, and standard Node.js.

The primary users are backend Node.js services that load configuration at startup, build tools that parse pipeline definitions, and frontend bundler plugins that read YAML data files. TypeScript projects benefit immediately because the package ships its own type declarations under dist/js-yaml.d.ts, with no separate @types installation required.

The library is versioned at 5.4.2, is authored in TypeScript (visible in the top-level tsconfig.json and src/ directory), and distributes both a compiled CommonJS bundle and an ES module bundle so it fits equally well in older require-based codebases and modern import-based ones.

How load and dump Process YAML

js-yaml exposes two primary named exports: load and dump. load() takes a YAML string and returns the corresponding JavaScript value. A plain mapping becomes a plain object, a sequence becomes an array, and scalar values map to their JavaScript equivalents. dump() does the reverse: it takes a JavaScript value and returns a YAML string.

Both functions are named exports, not a default export. The README shows the pattern clearly:

import { load } from 'js-yaml'

try {
  const document = load('greeting: hello')
  console.log(document.greeting)
} catch (e) {
  console.error(e)
}

The library throws a typed error when the input is invalid YAML, so wrapping calls in try/catch is the expected pattern, not an optional precaution.

For the reverse direction:

import { dump } from 'js-yaml'

const source = dump({ greeting: 'hello' })
console.log(source)

dump() produces a human-readable YAML string. The project documentation site at nodeca.github.io/js-yaml/doc/ covers additional options for both functions, including indent control and custom type handling. The README links to that site for full usage examples beyond the basic cases shown above.

Installing js-yaml and Running a First Parse

Installation is a single npm command:

npm install js-yaml

The package ships under the name js-yaml on npm. After installation, the ESM entry point is dist/js-yaml.mjs and the CommonJS entry point is dist/js-yaml.cjs.js. The package.json exports field maps the bare import to the correct format automatically, so bundlers and runtimes pick up the right build without manual configuration.

For browser use, the package also ships minified builds. The exports field exposes a ./browser sub-path that resolves to dist/browser/js-yaml.esm.min.mjs for ESM consumers and dist/browser/js-yaml.umd.min.js for UMD consumers. A project that loads js-yaml via a CDN tag can use the UMD build directly without a bundler.

The package also installs a CLI tool. The bin entry in package.json registers js-yaml as a command, backed by bin/js-yaml.mjs. This allows piping YAML files through the command line for quick inspection or conversion. The README does not document the CLI flags; the full flag reference is in the documentation site.

YAML 1.2 and 1.1 Coverage and the Test Suite

YAML has two active specification versions. YAML 1.1 was the dominant version for years and is what most legacy tools target. It has a number of parsing quirks: bare values like yes and no resolve to boolean true and false, and octal literals use a different prefix syntax. YAML 1.2 corrected those ambiguities and is the version published in 2009.

js-yaml supports both. This matters when a project reads configuration files generated by older tooling that follows YAML 1.1 conventions, or when interoperating with systems written in Python or Ruby that may output 1.1-style documents.

The stronger claim the project makes is that it passes the entire YAML Test Suite maintained at github.com/yaml/yaml-test-suite. The YAML Test Suite is the canonical reference test set for YAML implementations, covering edge cases across both spec versions. The project's CI configuration (visible in the .github/ directory) fetches the test suite as part of the test run using support/get-yaml-test-suite.mjs, so passing the suite is verified on each commit, not just stated in documentation.

For most applications reading straightforward configuration files, this depth of spec coverage is not visible in day-to-day use. It matters most when the input YAML comes from an external source with unusual syntax, or when the parser needs to round-trip values without losing type information across spec boundaries.

Real Limitations of js-yaml

The README is intentionally minimal. It shows two function calls and links to an external documentation site. This means a developer who reads only the README will not know the full option surface for load() or dump(). For example, the README does not document whether load() supports multi-document YAML files (files that contain multiple documents separated by ---), nor does it document how to configure custom type constructors. Those answers require reading the external docs site.

The project has no GitHub releases. The release history lives entirely on npm, where the version field in package.json reads 5.4.2. There is a CHANGELOG.md in the repository, but version updates are not surfaced as GitHub Release entries, which makes it harder to subscribe to release notifications through GitHub's native tooling.

The package carries no bundled schema validation. It parses YAML into JavaScript values but does not validate the resulting structure against a schema. A project that needs to enforce that a parsed config matches a defined shape must add a separate validation library such as zod or ajv after parsing.

Finally, the benchmark/ directory in the repository indicates performance work was done, but the README does not publish benchmark numbers, so there is no documented performance baseline to compare against.

How js-yaml Compares to the yaml Package

The npm ecosystem has a second prominent YAML library for JavaScript called yaml (the package name is just yaml, not js-yaml). Both parse and serialize YAML, and both support YAML 1.2. The qualitative difference is in the design philosophy.

The yaml package provides a document-oriented API that preserves comments and blank lines from the source file when round-tripping a document. This is important for tools that read a YAML file, modify a value, and write the file back while keeping the existing comments intact. js-yaml does not advertise comment preservation in its README or documentation summary, and the load/dump API is value-oriented rather than document-oriented.

js-yaml's stated focus is on correctness against the YAML Test Suite and providing a simple load/dump interface. The yaml package emphasizes document fidelity. A project that treats YAML files as pure data (read once, discard the string) is well served by js-yaml. A project that acts as a YAML editor, reading and then writing back with modifications while keeping the file human-readable, should look at the yaml package instead.

Both are MIT licensed. The choice comes down to whether comment and whitespace preservation matters for the specific use case.

Module Formats, TypeScript Declarations, and the CLI

js-yaml ships four distinct build artifacts from the same source. The main entry is a CommonJS bundle at dist/js-yaml.cjs.js for Node.js projects using require(). The module entry is an ES module at dist/js-yaml.mjs for projects using import. Browser-specific minified builds live at dist/browser/js-yaml.esm.min.mjs (ESM) and dist/browser/js-yaml.umd.min.js (UMD). All four are covered by the same TypeScript declarations file at dist/js-yaml.d.ts.

The presence of built-in TypeScript declarations means that in versions shipping those declarations, there is no need to install a separate @types/js-yaml package. The types are bundled with the library itself. TypeScript consumers get autocomplete and type checking for load() and dump() without additional configuration.

The package registers a CLI entry point under the name js-yaml via the bin field in package.json. This means after installing the package globally or using npx, the js-yaml command is available on the command line. The CLI is useful for quick manual inspection of YAML files without writing a script. The README does not document the available flags; the documentation site covers the full option set.

The project is MIT licensed, which imposes no restrictions on commercial use, modification, or redistribution.

Editorial conclusion

js-yaml is the right choice for Node.js projects that parse YAML configuration files and need confirmed spec coverage across YAML 1.1 and 1.2 inputs. Browser-side code can use the dedicated UMD or ESM build without a bundler adjustment. TypeScript projects get type declarations from the package itself. Projects that require comment preservation during a round-trip parse or need to process YAML streams document-by-document should check the yaml package before committing, because the README does not document either capability for js-yaml. Confirm the full API on the documentation site at nodeca.github.io/js-yaml/doc/ before relying on behaviour not shown in the README.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository