js-yaml 5.5.0: load and dump for YAML 1.2 and 1.1, four builds behind one exports map, and no GitHub releases

load and dump are the whole everyday API

js-yaml installs from npm under its own name:

npm install js-yaml

Reading YAML is a call to load, which takes a YAML string and returns a JavaScript value:

import { load } from 'js-yaml'

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

Writing YAML is the reverse, dump takes an object and returns a YAML string:

import { dump } from 'js-yaml'

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

Both are named exports, imported with ESM syntax. The package.json description sums the project up as a YAML 1.2 parser and serializer, and those two functions are the parser and the serializer. Anything beyond them, such as options for either call, lives in docs/usage.md and the API documentation at nodeca.github.io/js-yaml/doc/.

load throws on bad input, so every parse needs a catch

The usage example wraps load in try and catch for a reason. load does not return an error value or null when the input is not valid YAML; it throws. In a script that means a stack trace and an exit. In a server that parses user-uploaded YAML, a configuration file a user can edit, or a request body, an uncaught throw from load can take down the request or the process, depending on how your framework handles exceptions.

The practical rule is to treat load as an operation that can fail on any input you do not fully control, and to decide where that failure is reported. The example logs the error with console.error. A web handler would turn the same error into a 400 response. A build tool would print the file name with the error so the author can fix the YAML. The online demo at nodeca.github.io/js-yaml/ is a quick place to see how a given input fails before writing that handling.

YAML 1.2 by default name, with 1.1 support and the full YAML Test Suite as the bar

js-yaml supports both the YAML 1.2 and YAML 1.1 specifications, and it passes the entire YAML Test Suite, the shared conformance suite hosted at github.com/yaml/yaml-test-suite. The tagline and the package.json description both call it a YAML 1.2 parser. Its keywords also include pyyaml, which places it next to the Python library many YAML users already know.

Supporting two specs has a consequence for anyone migrating files between tools. The 1.1 and 1.2 specs do not read every document the same way, so the same file can produce different JavaScript values depending on which spec applies. Before relying on 1.1 behavior from older configuration files, check in docs/usage.md and the API documentation how a load call selects the spec, and test the files that matter to you in the online demo.

One package, four builds behind the exports map

The npm package publishes only two folders, bin/ and dist/, and its exports map routes each environment to a different build. A plain import of js-yaml resolves to dist/js-yaml.mjs, a require resolves to dist/js-yaml.cjs.js, and both share the type definitions in dist/js-yaml.d.ts. The legacy main, module and types fields point at the same three files for tools that do not read exports.

A second entry point, js-yaml/browser, serves minified builds: dist/browser/js-yaml.esm.min.mjs for import, and dist/browser/js-yaml.umd.min.js for require and as the default. The UMD file is the one to reach for when loading js-yaml without a bundler.

Because dist/js-yaml.d.ts ships inside the package, TypeScript projects get types from js-yaml itself. Only paths listed in the exports map are importable, so deep imports into internal files from older code will not resolve.

A js-yaml command ships alongside the library

The bin field maps a js-yaml command to bin/js-yaml.mjs, and bin/ is one of the two folders the package publishes. Installing js-yaml therefore also installs a command line entry point, usable through npx or from a project's npm scripts.

The README front page stays on the library API and does not show the command's arguments. To use the CLI in a pipeline, read bin/js-yaml.mjs or the documentation site for its options rather than guessing them. Since the file is an .mjs module, it runs as ESM under Node.

No GitHub releases: versions come from npm and CHANGELOG.md

The repository has no GitHub releases. Version numbers live in package.json, which currently reads 5.5.0, and in npm's published versions; the history of changes lives in CHANGELOG.md at the repository root. The default branch is master, and the last push was on 2026-10-27.

This matters for upgrades. A GitHub watch on releases will never fire, so dependency bots and npm are the signals to rely on. It also matters for anyone arriving from older guides: questions about js-yaml 4.3.1 and 4.3.2 still circulate, while the source tree is on the 5.x line and written in TypeScript. Before upgrading across a major version, read CHANGELOG.md for the entries between your installed version and 5.5.0, and run your own YAML fixtures through load and dump on the new version before shipping.

The test suite is fetched at test time, and speed is claimed without numbers

For contributors, npm test is a chain: lint with ESLint, build, type-check with tsc --noEmit, fetch the YAML Test Suite with spec:get, then run node --test over test/core/**/*.test.mjs and test/spec/*.test.mjs. spec:get runs node support/get-yaml-test-suite.mjs, so the conformance tests depend on that script retrieving the suite before they can run. test:spec runs only the spec tests after a build. Documentation is generated from typedoc.config.mjs.

The repository description calls js-yaml very fast, and a benchmark/ folder sits at the root, but no figures accompany the claim on the README. If parse speed matters for your workload, such as large manifests or many files per build, run your own inputs through load and measure, rather than treating the description as a number you can plan around.

Editorial conclusion

js-yaml suits Node and browser projects that need to read and write YAML with two functions, ship ESM, CommonJS or UMD from one package, and get type definitions without a separate install. It is a poor fit if you track upgrades through GitHub releases, since there are none, or if you need performance figures before choosing, since the speed claim comes without numbers. Before adopting or upgrading, read CHANGELOG.md for the jump between your installed major and 5.5.0, confirm in the documentation which YAML spec version your load calls follow, and wrap every load in error handling.

Frequently asked questions

Official sources

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