monaco-yaml

monaco-yaml adds full YAML language support to Monaco Editor (the editor that powers VS Code), including syntax validation, hover documentation, and autocompletion driven by JSON Schema. Since YAML has no native schema mechanism of its own, the plugin lets consumers attach JSON Schemas to YAML documents by URI pattern, giving users VS Code-quality YAML editing (think Kubernetes manifests or GitHub Actions workflows) inside any web application.

It runs the actual language service in a Web Worker (via yaml.worker) so parsing and validation don’t block the UI thread, mirroring how Monaco’s own JSON and TypeScript language services are architected. It’s the standard choice whenever a web app embeds Monaco and needs to edit YAML with the same fidelity users expect from VS Code.

What You Get

• Real-time YAML syntax and schema validation with inline diagnostics
• JSON Schema-driven autocompletion and hover documentation for YAML keys and values
• Schema association by file URI pattern (glob), so different YAML files can validate against different schemas
• A dedicated yaml.worker Web Worker so parsing/validation never blocks the main UI thread
• TypeScript typings and ESM-first packaging for straightforward integration into modern bundler setups

Common Use Cases

• Building a web-based configuration editor (Kubernetes manifests, CI pipeline files, OpenAPI specs) with schema-validated YAML editing
• Embedding VS Code-quality YAML autocompletion in an internal developer tool or low-code platform
• Adding YAML support to a browser-based IDE or playground that already uses Monaco for JSON/TypeScript editing
• Validating user-authored YAML against a custom JSON Schema in real time before it’s submitted or saved

Under The Hood

Architecture The plugin follows Monaco’s own language-service pattern: src/index.ts registers the YAML language and exposes the public configuration API (schema associations, options), while src/yaml.worker.ts runs the actual parsing, validation, and completion logic inside a Web Worker created via monaco-worker-manager, keeping expensive YAML/JSON-Schema processing off the main thread exactly as Monaco’s built-in JSON and TypeScript workers do; fillers/ provides browser-safe shims for Node built-ins the worker’s dependencies expect (e.g. path-browserify for path).

Tech Stack TypeScript (ESM-only, type: module), built with tsc plus a custom build.js for asset/worker bundling, tested with Vitest; it depends on a small constellation of purpose-built companion packages by the same maintainer (monaco-worker-manager, monaco-languageserver-types, monaco-marker-data-provider, monaco-types) alongside jsonc-parser for JSON-with-comments parsing and @vscode/l10n for localization, plus prettier for YAML formatting support.

Code Quality The test/ directory (e.g. marker-data.test.ts) exercises diagnostic/marker generation against real YAML+schema fixtures, and the package ships full TypeScript typings alongside its ESM build; the project maintains a documented example workspace (examples/) that doubles as an integration smoke test and a live demo site (monaco-yaml.js.org).

API Design The public API centers on a single configureMonacoYaml() call that takes schema associations and validation options, which is a low-friction entry point for the common case, though correctly wiring the Web Worker (via bundler-specific worker loader configuration) is the one non-trivial setup step most new users hit, documented extensively in the README precisely because bundler worker configuration varies (Vite, webpack, esbuild each need slightly different worker setup).