⚡ lightning-yaml

Spec-compliant YAML parsing, out to give JSON.parse a run for its money.

⚡ ~4× faster and ~1.1–2.6× lighter than js-yaml (bigger file, bigger gap) — with near-JSON.parse memory even at 10 MB. See the benchmarks ↓

lightning-yaml is a pure-JS YAML 1.2 parser and stringifier that parses and writes at speeds approaching native JSON.parse/JSON.stringify — while faithfully implementing YAML 1.2, passing ~97.6% (364/373) of the official yaml-test-suite. It's an API-level drop-in for either — same exports and call signatures, ESM + CJS + full TypeScript types, and zero runtime dependencies. No more trading YAML's readability for JSON's performance.

Two goals, in priority order: (1) full YAML 1.2 spec compliance, then (2) speed and memory within reach of native JSON.parse/JSON.stringify. Everything else is secondary to those two.

• Fast. Parses and stringifies at speeds approaching native JSON.parse/JSON.stringify — 3–5× faster than js-yaml on parse, across our benchmark workloads.
• Spec-compliant. Faithfully implements YAML 1.2 — passes ~97.6% (364/373) of the official yaml-test-suite.
• Drop-in (API-level). Same exports and signatures as yaml and js-yaml — swap the import and your code runs. Option arguments (schema, sortKeys, indent, …) are accepted-but-ignored today; see Drop-in.
• Lean. Zero runtime dependencies, small bundle; ships ESM + CJS + full TypeScript types.
• Complete. Full YAML 1.2 core — flow & block syntax, anchors/aliases, tags incl. !!binary, multi-document streams, and more.

Benchmarks at a glance

Measured primarily against native JSON.parse — the bar this project holds itself to — with js-yaml and yaml for context. Representative figures on the maintainer's machine; the full tables (all datasets, every parser, tracked over time) live at lightning-yaml.dev, reading published runs from the orphan benchmark-data branch.

| Representative metric | JSON.parse | lightning-yaml | js-yaml | yaml | | -------------------------- | -----------: | -----------------: | -------: | ------: | | Parse — large records | 8.6 ms | 19.2 ms | 104 ms | 964 ms | | Peak RSS — 10 MB document | 284 MB | 369 MB | 975 MB | 2.68 GB | | Bundle — minified / gzip | native | 40 KB / 12 KB | 52/16 KB | 96/29 KB |

That's roughly 2× JSON.parse's parse time and ~1.3× its peak memory on large inputs — versus ~12× / ~3.4× for js-yaml and ~110× / ~9.6× for yaml.

Full benchmarks (all datasets, every parser) → lightning-yaml.dev

Install

pnpm add lightning-yaml
npm install lightning-yaml
yarn add lightning-yaml
bun add lightning-yaml

Browser / CDN — no build step required:

<script src="https://cdn.jsdelivr.net/npm/lightning-yaml/dist/lightning-yaml.min.js"></script>
<script>
  const data = YAML.parse('greeting: hello');
</script>

Or as modern ESM, straight from a CDN:

import { parse } from 'https://cdn.jsdelivr.net/npm/lightning-yaml/+esm';

ESM, CommonJS, and TypeScript types all ship in the box.

Quick start

import { parse, parseAll, stringify } from 'lightning-yaml';

parse(`
name: lightning-yaml
version: 0.1.0
features: [fast, spec-compliant, drop-in]
`);
// → {
//     name: 'lightning-yaml',
//     version: '0.1.0',
//     features: ['fast', 'spec-compliant', 'drop-in'],
//   }

stringify({ hello: 'world', list: [1, 2, 3] });
// → hello: world
//   list:
//     - 1
//     - 2
//     - 3

parseAll(`
---
a: 1
---
b: 2
`);
// → [{ a: 1 }, { b: 2 }]   ← multi-document streams

Full API reference and function signatures → lightning-yaml.dev

Drop-in for js-yaml or yaml

Already using another YAML library? Swap one import, keep your code.

// Coming from js-yaml — comment out the old import:
// import { load, dump } from 'js-yaml';
import { load, dump } from 'lightning-yaml/js-yaml';

// Using the `yaml` library — same idea:
// import { parse, stringify } from 'yaml';
import { parse, stringify } from 'lightning-yaml/yaml';

Status — surface-level today. The shims are a TypeScript drop-in (same exports and signatures), so your code compiles and runs — but option arguments (schema, sortKeys, indent, …) are currently accepted-and-ignored. Full option compatibility is the goal; each shim's option-support matrix (js-yaml, yaml) lists which options are easy or hard to support next.

Project priorities

In order:

1. Compliance with the YAML 1.2 specification. Correctness comes first, always — a fast parser that mis-reads your config is worthless. Where the spec itself is unclear, the yaml-test-suite is our north star; where even that is ambiguous, we fall back to matching the behaviour of the yaml and js-yaml libraries.
2. Speed and memory within reach of native JSON.parse / JSON.stringify. We'll never match native byte-for-byte, and we know it — but we treat that gap as a bug to shrink, chasing every last nanosecond so there's no performance reason left to reach for JSON over YAML.

Contributing & feedback

lightning-yaml is young, and the single most useful thing you can do is try it and tell me what happens — I'm hugely grateful to anyone who gives it a run.

• Try to break it. Find some YAML that crashes the parser, or that it reads in a way the YAML 1.2 spec doesn't? I'd be thrilled to hear about it — open an issue with the input and I'll be on it fast. Real-world edge cases are exactly what make this library better.
• Slower than you expected? If lightning-yaml is slower than another YAML parser on your data, slower than the benchmarks suggest, or just doesn't work in your environment, please open an issue — I'd genuinely love to dig into it.
• Spot a claim that doesn't hold up? If a benchmark looks wrong, a number or claim reads as inaccurate, or we're configuring js-yaml or yaml in a way that's unfair to them — where a fairer setup would make them look faster — I want to know. Open an issue: benchmark honesty and accuracy matter more here than looking good, and I'll fix anything that's off.
• Ideas, questions, or just want to chat? GitHub Discussions is the place for anything that would make the library better.

I care a lot about making this the best YAML parser it can be, and I'll move quickly on whatever you find.

Sending a pull request? See CONTRIBUTING.md — in short, if you change anything under src/, run pnpm changeset to declare the version bump; CI checks for it.

Status & scope

YAML 1.2 core, feature-complete but for one deliberate gap — merge keys (<<). Today a << key is read as an ordinary string key rather than being merged (it's neither expanded nor rejected); everything else in the 1.2 core is implemented.

lightning-yaml passes ~97.6% of the official yaml-test-suite (364/373) — a faithful implementation of YAML 1.2 core. The handful of remaining failures are unrelated spec edge cases, not merge keys (the suite doesn't exercise <<).

Built with Claude Code

lightning-yaml is built with the help of Claude Code, but every commit is human-reviewed and I'm accountable for all of the code. The aim is the leverage of AI without a vibe-coded, unreviewed repo — the assistant helps write it, a human owns it. You'll also see a steady stream of commits that do nothing but tidy up: keeping the code human-readable and maintainable is an ongoing priority, not an afterthought.

License

Apache License 2.0 — © 2026 Joseph Siddall.

Design, benchmarks & internals

How lightning-yaml is built, measured, and tested — the benchmark methodology, the separate peak-memory harness, the consistency suite, and the parser internals — lives in the docs, so this README stays focused on using the library:

• lightning-yaml.dev → — guides, benchmarks, the full API reference, and the design write-ups.
• Try it live → — paste in YAML or JSON and see what lightning-yaml produces, side by side with js-yaml and yaml.