eslint-plugin-yaml

1.1.3 verified Fri May 01 auth: no javascript

An ESLint plugin that provides linting for YAML files (`.yaml`, `.yml`). Current stable version is 1.1.3, released March 2025. It uses an ESLint-based YAML parser (not js-yaml) since v1.1.0, enabling integration with ESLint's rule system. Supports both ESLint 9 flat config (ESM/CJS) and legacy ESLint 8 configs. Ships TypeScript types. Differentiators: first-class ESLint compatibility with YAML-specific rules, support for multiple YAML documents, and active maintenance with recent dependency updates.

Common errors

error Cannot find module 'eslint-plugin-yaml' ↓

cause Package not installed or not in node_modules.

fix

Run npm install eslint-plugin-yaml --save-dev.

error Error: Plugin 'yaml' was conflicted between 'eslint-plugin-yaml' and ... ↓

cause Multiple versions or duplicate plugin registrations.

fix

Ensure only one version is installed and remove duplicate overrides.

error TypeError: Cannot read properties of undefined (reading 'configs') ↓

cause Using CommonJS require without .default to access default export.

fix

Use require('eslint-plugin-yaml').default instead of require('eslint-plugin-yaml').

error ESLint couldn't find the config 'plugin:yaml/legacy'. ↓

cause Using legacy config string with ESLint 9 or plugin version 1.0+.

fix

Use flat config with pluginYaml.configs.recommended.

Warnings

breaking v1.1.0 rewrote the parser from js-yaml to an ESLint-based parser; rules and behavior may differ. ↓

fix Review rule configurations; update custom parser settings if any.

breaking v1.0.0 dropped support for ESLint 8 and flat config is required. ↓

fix Use ESLint 9+ and migrate to eslint.config.js/flat config.

breaking v0.5.0 dropped Node 10 support. ↓

fix Use Node >=12.

deprecated Legacy .eslintrc config (plugin:yaml/legacy) is deprecated in favor of flat config. ↓

fix Migrate to flat config with pluginYaml.configs.recommended.

gotcha CommonJS require must use .default: const pluginYaml = require('eslint-plugin-yaml').default ↓

fix Use .default for CommonJS, or use ESM import.

Install

npm install eslint-plugin-yaml

yarn add eslint-plugin-yaml

pnpm add eslint-plugin-yaml

Imports

pluginYaml
wrong
```
const pluginYaml = require('eslint-plugin-yaml')
```
correct
```
import pluginYaml from 'eslint-plugin-yaml'
```
Default export is the plugin object. For CommonJS, use require('eslint-plugin-yaml').default.
configs.recommended
wrong
```
require('eslint-plugin-yaml').configs.recommended
```
correct
```
import pluginYaml from 'eslint-plugin-yaml'; pluginYaml.configs.recommended
```
For flat config (ESLint 9+), use default import and access .configs.recommended. Legacy config uses plugin:yaml/legacy.

rules

wrong

require('eslint-plugin-yaml').rules

correct

import pluginYaml from 'eslint-plugin-yaml'; pluginYaml.rules

Rules are available as a map on the plugin object.

Quickstart

Shows how to use eslint-plugin-yaml with ESLint 9 flat config, importing the plugin and applying its recommended config plus custom rules.

// eslint.config.mjs (ESLint 9+)
import pluginYaml from 'eslint-plugin-yaml';

export default [
  pluginYaml.configs.recommended,
  {
    rules: {
      'yaml/no-empty-key': 'error',
      'yaml/no-empty-value': 'error',
    }
  }
];

// Then lint: npx eslint .