usage.md

title	Usage examples
category	Main

Usage examples

Load

Basic usage

Read files explicitly as UTF-8 and pass the filename to load() so parse errors identify the input source:

import { readFileSync } from 'node:fs'
import { load } from 'js-yaml'

const filename = 'config.yml'

try {
  const source = readFileSync(filename, 'utf8')
  const config = load(source, { filename })

  console.log(`Starting ${config.service.name} on port ${config.service.port}`)
} catch (e) {
  console.error(e instanceof Error ? e.message : String(e))
  process.exitCode = 1
}

For a stream containing several YAML documents, use loadAll():

import { loadAll } from 'js-yaml'

try {
  const documents = loadAll(`
---
name: api
port: 8080
---
name: worker
concurrency: 4
`)

  console.log(documents)
} catch (e) {
  console.error(e)
}

Unlike load(), loadAll() accepts empty and multi-document streams. It returns an array; an empty stream produces an empty array.

Schema customization

The most frequent cases are:

• enabling merge keys;
• replacing the default object maps with native Map instances.

Here is how to do that:

import { CORE_SCHEMA, mergeTag, realMapTag } from 'js-yaml'

const schema = CORE_SCHEMA.withTags(mergeTag, realMapTag)

Alternate map tag

For the most robust object-based mappings, use objects without a prototype and accept only string keys:

import { CORE_SCHEMA, load, mapTag } from 'js-yaml'

const schema = CORE_SCHEMA.withTags({
  ...mapTag,
  create: () => Object.create(null),
  addPair: (container, key, value) => {
    if (typeof key !== 'string') return 'object-based map supports only string keys'
    container[key] = value
    return ''
  },
  has: (container, key) => typeof key === 'string' && key in container,
  get: (container, key) => {
    if (typeof key !== 'string' || !(key in container)) return null
    return container[key]
  }
})

try {
  const config = load('{ enabled: true, level: 2 }', { schema })
} catch (e) {
  console.error(e)
}

This is not the default because objects without a prototype break many common usage examples and equality checks. Still, consider using realMapTag instead.

Dump

Basic usage

dump() returns a YAML string with a trailing newline:

import { dump } from 'js-yaml'

const config = {
  service: { name: 'api', ports: [8080, 8081] },
  logging: { level: 'info' }
}

const output = dump(config, { lineWidth: 100 })

console.log(output)

Unsupported values, such as functions, cause an exception by default. Use skipInvalid: true only when silently dropping those values is intentional.

Formatting scalar values

Use DUMP_SCHEMA as the base so its compatibility and quoting rules remain active.

import { DUMP_SCHEMA, boolYaml11Tag, dump, nullYaml11Tag } from 'js-yaml'

// Instead of defining a new tag, we override a single method of clone
// in one line. That's compact and simple.
const schema = DUMP_SCHEMA.withTags(
  { ...boolYaml11Tag, represent: value => value ? 'TRUE' : 'FALSE' },
  { ...nullYaml11Tag, represent: () => '' }
)

const output = dump({
  enabled: true,
  archived: false,
  parent: null
}, { schema })

console.log(output)

Output:

enabled: TRUE
archived: FALSE
parent:

CLI

The CLI is intentionally minimal, with no plans to extend its feature set.

npx js-yaml -h