node-yaml

library4.0.1jsnpmunverified

node-yaml is a streamlined wrapper library for the popular js-yaml parser, simplifying file-based YAML operations in Node.js environments. It provides convenient asynchronous and synchronous methods like `read`, `write`, `readSync`, and `writeSync` for handling YAML files. The current stable version is 4.0.1. Released with native ESM support in v4.0.0, it shifted js-yaml to a peer dependency, requiring manual installation of js-yaml. It aims for a stable, active release cadence, indicated by recent minor updates following a major rewrite. Its key differentiator is abstracting away the boilerplate of file system operations when working with YAML data, making it easier to parse and serialize YAML to and from files compared to directly using js-yaml's `safeLoad` and `safeDump` functions with `fs` module operations.

serialization data

npm install node-yaml

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-YAML

node-yaml

serializationjavascriptv4.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

read

✓ import { read } from 'node-yaml'

✗ const { read } = require('node-yaml')

ESM-only since v4.0.0. The `read` function always returns a Promise in v4 and later.

readSync

✓ import { readSync } from 'node-yaml'

✗ const { readSync } = require('node-yaml')

ESM-only since v4.0.0. This provides a synchronous API for reading YAML files.

write

✓ import { write } from 'node-yaml'

✗ const { write } = require('node-yaml')

ESM-only since v4.0.0. The `write` function always returns a Promise in v4 and later.

This example demonstrates how to write a JavaScript object to a YAML file and then read it back using both explicit and implicit file extensions, utilizing `node-yaml`'s asynchronous API.

import { read, write } from 'node-yaml'; import { rm, mkdir } from 'node:fs/promises'; import { join } from 'node:path'; const testDir = join(process.cwd(), 'temp_yaml_test'); const filePath = join(testDir, 'config.yaml'); async function runExample() { await rm(testDir, { recursive: true, force: true }); await mkdir(testDir, { recursive: true }); const config = { database: { host: 'localhost', port: 5432, user: 'admin' }, settings: { debug: true, logLevel: 'info' } }; try { // Write the YAML content to a file await write(filePath, config); console.log(`YAML content written to ${filePath}`); // Read the YAML content back from the file const readConfig = await read(filePath); console.log('\nFile content:\n%s', JSON.stringify(readConfig, null, 2)); // Demonstrate omitting file extension (if 'config.yaml' exists) const readConfigNoExt = await read(join(testDir, 'config')); console.log('\nFile content (no extension):\n%s', JSON.stringify(readConfigNoExt, null, 2)); } catch (err) { console.error('Error during YAML operations:\n%s', String(err)); } finally { await rm(testDir, { recursive: true, force: true }); console.log(`Cleaned up ${testDir}`); } } runExample();

Debug

Known issues

breakingStarting with v4.0.0, `js-yaml` is no longer a direct dependency but a peer dependency. You must install `js-yaml` manually alongside `node-yaml`.

fix

Run `npm install node-yaml js-yaml` or `yarn add node-yaml js-yaml`.

affects: >=4.0.0

breakingVersion 4.0.0 introduced native ESM support and removed CommonJS `require()` support. Imports must use `import ... from 'node-yaml'` syntax.

fix

Migrate all `require()` statements to `import` statements and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

affects: >=4.0.0

breakingIn v4.0.0, the `write()` and `read()` functions were updated to always return Promises, removing the previously supported callback API. All calls to these functions must now be handled with `await` or `.then()/.catch()`.

fix

Refactor code to use `async/await` or Promise chains (`.then().catch()`) for `read()` and `write()` calls.

affects: >=4.0.0

breakingVersion 4.0.0 removed re-exported utilities and schemas from `js-yaml` (e.g., `parser`, `createSchema`, custom schemas). These must now be imported directly from `js-yaml` if needed.

fix

Modify imports to fetch specific `js-yaml` utilities directly from the `js-yaml` package, e.g., `import { Type } from 'js-yaml';`.

affects: >=4.0.0

gotchaThe `read` and `readSync` methods allow omitting the file extension. If multiple files with the same name but different extensions exist (e.g., `config.yaml`, `config.yml`), the first matched file will be read, which might not be the intended one.

fix

Always provide the full file path including the extension for clarity and to prevent ambiguity, especially when multiple files with similar names might exist.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'js-yaml' from 'node-yaml/lib/index.js'

Missing `js-yaml` peer dependency after upgrading to v4.0.0 or later.

fix

Install `js-yaml` manually: `npm install js-yaml` or `yarn add js-yaml`.

TypeError: require is not a function

Attempting to use `require()` with `node-yaml` in an ESM context after v4.0.0. The package is now ESM-only.

fix

Change `const { read } = require('node-yaml')` to `import { read } from 'node-yaml'` and ensure your project is configured for ESM.

TypeError: Cannot read properties of undefined (reading 'then')

Calling `read()` or `write()` without `await` or `.then()` in v4.0.0+, expecting a direct return value while the functions now return Promises.

fix

Update your code to correctly handle Promises, e.g., `const data = await read('file.yaml');` or `read('file.yaml').then(data => ...);`.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

js-yamlrequiredCore parsing and serialization engine; moved to a peer dependency in v4.0.0.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/octet-stream/node-yaml ↗

packagehttps://www.npmjs.com/package/node-yaml ↗