eslint-plugin-yml

eslint-plugin-yml is an ESLint plugin that provides linting rules for YAML files. Unlike some other YAML plugins that use processors to return results independently, this plugin provides both the Abstract Syntax Tree (AST) and the source code text to the ESLint engine.

Key benefits of this approach include:

• Support for ESLint directive comments (e.g., # eslint-disable).
• Compatibility with plugins and rules that require source code text, such as eslint-plugin-prettier or eol-last.
• Support for Vue SFC custom blocks like <i18n lang="yaml"> (requires vue-eslint-parser v7.3.0+).
• Real-time checking via editor integrations.

When YAML anchors and aliases are used, the rule might report or move properties even if they are configured with { type: ignore }.

While ignore prevents the property from being compared for ordering, it does not guarantee the property will remain fixed in place. This behavior is necessary to allow the rule to sort the remaining properties without accidentally moving an alias before its corresponding anchor.

To lint YAML files in JetBrains IDEs (like WebStorm), update the ESLint linting scope:

1. Open Settings/Preferences.
2. Navigate to Languages and Frameworks | JavaScript | Code Quality Tools | ESLint.
3. Select Automatic ESLint configuration or Manual ESLint configuration.
4. In the Run for files field, update the pattern to include YAML files (e.g., adding yaml,yml to the extension list).

{**/*,*}.{js,ts,jsx,tsx,html,vue,yaml,yml}

The yml/spaced-comment rule enforces consistent spacing after the # character in YAML comments. It is included in the configs.standard configuration. You can use the --fix flag with the ESLint CLI to automatically correct spacing issues.

Because the ESLint core spaced-comment rule does not work correctly in YAML, you should disable the core rule and enable yml/spaced-comment specifically for YAML files using an overrides block in your ESLint configuration.

module.exports = {
  overrides: [
    {
      files: ["*.yaml", "*.yml"],
      parser: "yaml-eslint-parser",
      rules: {
        "spaced-comment": ["off"],
        "yml/spaced-comment": ["error"],
      },
    },
  ],
};

The yml/flow-sequence-bracket-spacing rule enforces consistent spacing inside flow sequence brackets (e.g., [item1, item2]). This rule is included in the configs.standard configuration and supports the ESLint --fix option to automatically correct spacing issues.

# eslint yml/flow-sequence-bracket-spacing: 'error'

# ✓ GOOD
- [1, 2]

# ✗ BAD
- [ 1, 2 ]

The playground allows you to test YAML linting rules and see how they apply to your code in real-time without setting up a local environment. You can access the interactive playground at the link below.

https://ota-meshi.github.io/eslint-plugin-yml/playground/

The yml/no-trailing-spaces rule disallows trailing whitespace at the end of lines in YAML files. This rule is included by default in the configs.standard configuration. You can use the --fix flag with the ESLint command line to automatically remove trailing whitespace.

# eslint yml/no-trailing-spaces: 'error'

# ✓ GOOD
"GOOD": "foo"

# ✗ BAD
"BAD": "bar"
#         ^ trailing whitespace at the end of the previous line

The yml/key-name-casing rule enforces specific naming conventions for keys in your YAML files. By default, it only allows camelCase.

# eslint yml/key-name-casing: 'error'

# ✓ GOOD
"camelCase": "camelCase"

# ✗ BAD
"PascalCase": "PascalCase"
"SCREAMING_SNAKE_CASE": "SCREAMING_SNAKE_CASE"
"kebab-case": "kebab-case"
"snake_case": "snake_case"

To preserve the existing property order at specific paths (for example, to prevent breaking module resolution in package.json exports), use { type: ignore } in a configuration object placed before your fallback sorting rule.

yml/sort-keys:
  - error
  - pathPattern: '^exports\[".\"\].*'
    order: { type: ignore }
  - pathPattern: .*
    order: { type: asc }