eslint-plugin-yml

3.3.1 verified Sat Apr 25 auth: no javascript

An ESLint plugin that provides a comprehensive set of linting rules for YAML files, including support for Vue SFC custom blocks and ESLint directive comments. Version 3.3.1 is the latest stable release, with releases occurring every few months. Unlike other YAML linting plugins that use processors without providing AST and source code text to ESLint, eslint-plugin-yml provides full AST support, enabling ESLint directive comments and compatibility with other plugins like eslint-plugin-prettier. Requires Node.js 20+ and ESLint 9.38+.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/eslint-plugin-yml/dist/index.mjs from /path/to/eslint.config.js not supported. ↓

cause Using CommonJS require() to import an ESM-only module.

fix

Change require() to import statement: import eslintPluginYml from 'eslint-plugin-yml'

error Cannot find module 'eslint-plugin-yml' or its corresponding type declarations. ↓

cause The package does not include TypeScript definitions by default; you may need @types/eslint-plugin-yml.

fix

Install @types/eslint-plugin-yml as a dev dependency: npm install --save-dev @types/eslint-plugin-yml

error ConfigError: Config (flat): Key 'languageOptions' is not allowed for config at index 1. Use 'language' instead. ↓

cause Using deprecated languageOptions.parser in v3.0.0+.

fix

Replace languageOptions.parser with language: 'yml/yaml' in your config.

Warnings

breaking v3.0.0 changed shareable configs to use ESLint v9 language config API (language: 'yml/yaml') instead of legacy parser approach. Existing configs using languageOptions.parser will no longer work. ↓

fix Update your eslint.config.js to use the new language configuration (language: 'yml/yaml') instead of specifying parser in languageOptions.

deprecated The plugin only supports ESLint v8 or earlier with v1.x; from v2.0.0 onwards, it requires ESLint v9. ↓

fix Upgrade ESLint to v9.38.0 or later.

gotcha The plugin is ESM-only. Using require() will throw an error. ↓

fix Use import syntax or switch to dynamic import() for CommonJS projects if necessary.

gotcha When used with Vue SFC, vue-eslint-parser v7.3.0+ is required. Older versions are incompatible. ↓

fix Ensure vue-eslint-parser is at version 7.3.0 or higher.

Install

npm install eslint-plugin-yml

yarn add eslint-plugin-yml

pnpm add eslint-plugin-yml

Imports

default

wrong

const eslintPluginYml = require('eslint-plugin-yml')

correct

import eslintPluginYml from 'eslint-plugin-yml'

This plugin is ESM-only; CommonJS require is not supported.

configs

wrong

const { configs } = require('eslint-plugin-yml')

correct

import { configs } from 'eslint-plugin-yml'

Named export for accessing configs like configs.recommended.

rules
```
import { rules } from 'eslint-plugin-yml'
```
Named export for accessing individual rules if needed.

Quickstart

Configure ESLint to lint YAML files using the plugin's recommended config, then override specific rules.

import eslintPluginYml from 'eslint-plugin-yml';

export default [
  ...eslintPluginYml.configs.recommended,
  {
    rules: {
      'yml/block-mapping': 'error',
      'yml/no-empty-key': 'error',
    },
  },
];