阅读中文版本

Parse a YAML Config in a CLI

Load a YAML config with schema validation and helpful error messages so a malformed file fails clearly rather than silently.

import { readFileSync } from 'node:fs';
import { parse } from 'yaml';
const raw = parse(readFileSync('config.yaml', 'utf8'));
const result = schema.safeParse(raw);
if (!result.success) {
  console.error('config.yaml invalid:', result.error.issues.map(i => i.path.join('.')).join(', '));
  process.exit(2);
}

const schema = z.object({ host: z.string(), port: z.number().int() }).strict();

What this recipe does

Read a YAML config file and validate it against a schema with clear errors.

A typo in the config file is silently ignored, and the CLI runs with unexpected defaults.

Prerequisites

• A YAML parser and schema validator
• A config file convention
• A CLI entry point

Procedure

1. Parse YAML and validate against a schema.

import { readFileSync } from 'node:fs';
import { parse } from 'yaml';
const raw = parse(readFileSync('config.yaml', 'utf8'));
const result = schema.safeParse(raw);
if (!result.success) {
  console.error('config.yaml invalid:', result.error.issues.map(i => i.path.join('.')).join(', '));
  process.exit(2);
}

Expected result: A malformed config exits with a non-zero code and names the offending keys.

2. Fail fast on unknown keys.

const schema = z.object({ host: z.string(), port: z.number().int() }).strict();

Expected result: Typos surface as errors instead of being silently dropped.

How to confirm it worked

Run the commands above and confirm every expected result in order. If a step does not produce the stated output, use the troubleshooting notes before continuing. A passing run shows a config with an unknown key or wrong type exits non-zero and names the bad field.

Troubleshooting

Schema too strict breaks forward compatibility — Allow unknown keys only if the file is versioned and documented.

YAML quirks such as Norway problem — Quote ambiguous scalars and document formatting expectations.

Limitations

• Schema changes can break existing files.
• YAML has surprising type coercions.
• Does not cover secret interpolation.