YAML Libraries Compared: js-yaml vs yaml vs yamljs

YAML is a human-readable data serialization standard widely used for configuration files, data exchange, and infrastructure as code. In the JavaScript ecosystem, three main libraries have emerged to handle this format: js-yaml, yaml, and yamljs. While they all parse and stringify YAML, their underlying architectures, feature sets, and maintenance statuses differ significantly. Let's break down how they handle real-world engineering challenges.

🛡️ Security and Safety: Strict Modes vs Defaults

Security is paramount when parsing untrusted YAML, as malicious payloads can execute arbitrary code or overwrite object prototypes.

js-yaml provides explicit safety levels. You must choose between load (unsafe, allows custom tags) and loadAll with the SAFE_SCHEMA option to prevent dangerous constructs.

import * as yaml from 'js-yaml';

// Safe loading: rejects custom tags and JS functions
const data = yaml.load(inputString, { schema: yaml.DEFAULT_SAFE_SCHEMA });

// Unsafe loading: allows custom JS types (risky with untrusted input)
// const data = yaml.load(inputString);

yaml is secure by default. It does not execute arbitrary code or resolve custom tags unless explicitly configured to do so. Its API design discourages unsafe patterns.

import { parse } from 'yaml';

// Always safe by default; no custom tags resolved unless specified
const data = parse(inputString);

// To allow custom tags, you must explicitly define a schema
// const doc = new YAML.Document({ customTags: ... });

yamljs lacks modern safety features and clear separation between safe and unsafe modes. It relies on older patterns that may expose applications to prototype pollution if not carefully wrapped.

import YAML from 'yamljs';

// No explicit safe/unsafe schema option in the API
// Relies on internal implementation details that are less transparent
const data = YAML.parse(inputString);

🔄 Round-Trip Preservation: Comments and Formatting

When building tools that edit configuration files, preserving existing comments and indentation is often a requirement. Losing this metadata can frustrate users and destroy documentation embedded in config files.

js-yaml treats YAML as pure data. When you parse and then stringify, all comments and original formatting are lost. It outputs a canonical, clean version of the data.

import * as yaml from 'js-yaml';

const doc = yaml.load('# Comment here\nname: John');
const output = yaml.dump(doc);
// Output: "name: John\n" (Comment is gone)

yaml uses a tree-based representation (CST/AST) that retains comments, whitespace, and node details. You can modify a specific value and write the file back with comments intact.

import { parse, stringify, Document } from 'yaml';

const doc = new Document(parse('# Comment here\nname: John'));
doc.setIn(['name'], 'Jane');
const output = stringify(doc);
// Output: "# Comment here\nname: Jane\n" (Comment preserved)

yamljs behaves like js-yaml in this regard. It focuses on data extraction and does not preserve comments or formatting nuances during serialization.

import YAML from 'yamljs';

const data = YAML.parse('# Comment here\nname: John');
const output = YAML.stringify(data);
// Output: "name: John\n" (Comment is lost)

📜 Specification Support: YAML 1.1 vs 1.2

The YAML specification has evolved. YAML 1.2 clarified many ambiguities from 1.1, particularly regarding string quoting and boolean recognition.

js-yaml strictly follows YAML 1.2. It will not parse certain YAML 1.1 constructs (like unquoted yes/no as booleans) unless explicitly configured to use a legacy schema, ensuring predictable behavior.

import * as yaml from 'js-yaml';

// YAML 1.2: 'yes' is a string, not a boolean
const data = yaml.load('enable: yes');
console.log(data.enable); // Outputs: "yes" (string)

yaml supports both YAML 1.1 and 1.2. You can configure the version per document, making it flexible for legacy projects while defaulting to modern standards.

import { parse } from 'yaml';

// Default is 1.2, but you can specify 1.1
const data = parse('enable: yes', { version: '1.1' });
console.log(data.enable); // Outputs: true (boolean in 1.1)

yamljs is based on an older understanding of the spec and often behaves inconsistently with modern expectations. It does not offer clear version switching, leading to potential parsing surprises.

import YAML from 'yamljs';

// Behavior may vary; often treats 'yes' as boolean due to legacy 1.1 influence
const data = YAML.parse('enable: yes');
console.log(data.enable); // Likely outputs: true (inconsistent)

🏗️ Architecture and API Design

The way these libraries model YAML data affects how you interact with them.

js-yaml uses a functional, data-centric approach. You load a string into a plain JavaScript object and dump an object back to a string. It is simple and effective for stateless operations.

import * as yaml from 'js-yaml';

// Functional style: String -> Object -> String
const obj = yaml.load(fileContent);
obj.version = 2;
const newContent = yaml.dump(obj);

yaml uses a document-centric, object-oriented approach. It creates a Document object that represents the entire YAML structure, allowing granular manipulation of nodes before serialization.

import { Document } from 'yaml';

// OO style: Create Document -> Modify Nodes -> Serialize
const doc = new Document();
doc.contents = { name: 'Alice' };
doc.get(['name']).comment = 'User name';
const newContent = doc.toString();

yamljs uses a class-based wrapper around a parser that feels dated compared to modern ES6+ patterns. It often requires callback-style asynchronous loading for files, which clashes with modern async/await flows unless wrapped.

import YAML from 'yamljs';

// Callback-based file loading (legacy pattern)
YAML.load('config.yaml', function(result) {
  console.log(result);
});

// Or synchronous blocking call
// const result = YAML.load('config.yaml');

🚫 Deprecation Warning: The Case Against yamljs

yamljs has not seen significant updates in years. Its repository shows minimal activity, and it lacks support for modern features like ES modules without transpilation hacks. It does not handle complex YAML 1.2 features reliably.

Recommendation: If you are starting a new project, do not use yamljs. It poses a maintenance risk and offers no advantages over the other two options. For existing projects using yamljs, migrating to js-yaml (for simple data) or yaml (for tooling) should be a priority.

// ❌ Avoid this in new code
import YAML from 'yamljs'; 

// ✅ Prefer this instead
import { parse } from 'yaml';
// OR
import * as yaml from 'js-yaml';

🌐 Real-World Scenarios

Scenario 1: CI/CD Configuration Validation

You need to validate GitHub Actions or Kubernetes manifests in a pipeline. Security and strict spec compliance are key.

• ✅ Best choice: js-yaml
• Why? Its strict schema validation prevents accidental execution of malicious tags and ensures the config matches the expected standard.

import * as yaml from 'js-yaml';
try {
  const config = yaml.load(ciFile, { schema: yaml.DEFAULT_SAFE_SCHEMA });
  validateStructure(config);
} catch (e) {
  console.error('Invalid CI config', e);
}

Scenario 2: Configuration Editor GUI

You are building a UI that lets users edit a docker-compose.yml file. You must keep their comments and formatting.

• ✅ Best choice: yaml
• Why? Only yaml preserves the comments and structure when saving changes back to disk.

import { parse, stringify, Document } from 'yaml';
const doc = new Document(parse(fileContent));
doc.setIn(['services', 'web', 'image'], 'nginx:latest');
fs.writeFileSync('docker-compose.yml', stringify(doc));

Scenario 3: Legacy Script Migration

You found an old build script using yamljs that loads a config file synchronously.

• ✅ Action: Refactor to js-yaml or yaml.
• Why? yamljs uses callbacks and lacks modern safety. A quick swap improves reliability.

// Old
// const config = YAML.load('config.yaml');

// New
import * as yaml from 'js-yaml';
const config = yaml.load(fs.readFileSync('config.yaml', 'utf8'));

📊 Summary Table

💡 Final Recommendation

For most modern applications, the choice comes down to js-yaml vs yaml.

• Pick js-yaml if you treat YAML as a data transport format (like JSON) where you read data, process it, and don't care about the original file's comments or layout. It is fast, strict, and secure.
• Pick yaml if you are building developer tools, linters, or editors where the YAML file is a source of truth that humans edit. Its ability to preserve comments and formatting makes it indispensable for these use cases.

Avoid yamljs entirely. It belongs to an older era of JavaScript development and introduces unnecessary risk and limitation to your stack.