eslint-plugin-toml

Introduction

eslint-plugin-toml is ESLint plugin provides linting rules for TOML.

Features

This ESLint plugin provides linting rules for TOML.

• You can use ESLint to lint TOML.
• You can find out the problem with your TOML files.
• You can apply consistent code styles to your TOML files.
• Supports Vue SFC custom blocks such as <custom-block lang="toml">.
  Requirements vue-eslint-parser v7.3.0 and above.
• Supports ESLint directives. e.g. # eslint-disable-next-line
• You can check your code in real-time using the ESLint editor integrations.

You can check on the Online DEMO.

Documentation

See documents.

Installation

npm install --save-dev eslint eslint-plugin-toml

Requirements

• ESLint v9.38.0 and above
• Node.js v20.19.x, v22.13.x, v24.x and above

Usage

Configuration

Use eslint.config.js file to configure rules. See also: https://eslint.org/docs/latest/use/configure/configuration-files.

Example eslint.config.js:

import eslintPluginToml from 'eslint-plugin-toml';
export default [
  // add more generic rule sets here, such as:
  // js.configs.recommended,
  ...eslintPluginToml.configs.recommended,
  {
    rules: {
      // override/add rules settings here, such as:
    // 'toml/rule-name': 'error'
    }
  }
];

This plugin provides configs:

• *.configs.base ... Configuration to enable correct TOML parsing.
• *.configs.recommended ... Above, plus rules to prevent errors or unintended behavior.
• *.configs.standard ... Above, plus rules to enforce the common stylistic conventions.

For backward compatibility, you can also use the flat/* namespace:

• *.configs['flat/base']
• *.configs['flat/recommended']
• *.configs['flat/standard']

See the rule list to get the rules that this plugin provides.

Languages

This plugin provides the following language identifiers for use in ESLint configurations:

• toml/toml ... TOML files

For example, to apply settings specifically to TOML files, you can use the language field in your ESLint configuration:

import eslintPluginToml from 'eslint-plugin-toml';
export default [
  {
    files: ["*.toml", "**/*.toml"],
    plugins: {
      toml: eslintPluginToml,
    },
    language: "toml/toml",
  }
]

The configuration above is included in the shareable configs provided by this plugin, so using configs is generally recommended.

See also https://eslint.org/docs/latest/use/configure/plugins#specify-a-language

Editor Integrations

Visual Studio Code

Use the dbaeumer.vscode-eslint extension that Microsoft provides officially.

You have to configure the eslint.validate option of the extension to check .toml files, because the extension targets only *.js or *.jsx files by default.

Example .vscode/settings.json:

{
    "eslint.validate": [
        "javascript",
        "javascriptreact",
        "toml"
    ]
}

Rules

The --fix option on the command line automatically fixes problems reported by rules which have a wrench below.
The rules with the following star are included in the configs.

TOML Rules

Rule ID	Description	Fixable	RECOMMENDED	STANDARD
toml/indent	enforce consistent indentation
toml/keys-order	disallow defining pair keys out-of-order
toml/no-mixed-type-in-array	disallow mixed data types in array
toml/no-non-decimal-integer	disallow hexadecimal, octal and binary integer
toml/no-space-dots	disallow spacing around infix operators
toml/no-unreadable-number-separator	disallow number separators that to not enhance readability.
toml/padding-line-between-pairs	require or disallow padding lines between pairs
toml/padding-line-between-tables	require or disallow padding lines between tables
toml/precision-of-fractional-seconds	disallow precision of fractional seconds greater than the specified value.
toml/precision-of-integer	disallow precision of integer greater than the specified value.
toml/quoted-keys	require or disallow quotes around keys
toml/tables-order	disallow defining tables out-of-order
toml/vue-custom-block/no-parsing-error	disallow parsing errors in Vue custom blocks

Extension Rules

Rule ID	Description	Fixable	RECOMMENDED	STANDARD
toml/array-bracket-newline	enforce linebreaks after opening and before closing array brackets
toml/array-bracket-spacing	enforce consistent spacing inside array brackets
toml/array-element-newline	enforce line breaks between array elements
toml/comma-style	enforce consistent comma style in array
toml/inline-table-curly-newline	enforce linebreaks after opening and before closing braces
toml/inline-table-curly-spacing	enforce consistent spacing inside braces
toml/inline-table-key-value-newline	enforce placing inline table key-value pairs on separate lines
toml/key-spacing	enforce consistent spacing between keys and values in key/value pairs
toml/spaced-comment	enforce consistent spacing after the # in a comment
toml/table-bracket-spacing	enforce consistent spacing inside table brackets

Deprecated

• We're going to remove deprecated rules in the next major release. Please migrate to successor/new rules.
• We don't fix bugs which are in deprecated rules since we don't have enough resources.

Rule ID	Replaced by
toml/space-eq-sign	toml/key-spacing

Contributing

Welcome contributing!

Please use GitHub's Issues/PRs.

Development Tools

• npm test runs tests and measures coverage.
• npm run update runs in order to update readme and recommended configuration.

Working With Rules

This plugin uses toml-eslint-parser for the parser. Check here to find out about AST.

Related Packages

• eslint-plugin-jsonc ... ESLint plugin for JSON, JSON with comments (JSONC) and JSON5.
• eslint-plugin-yml ... ESLint plugin for YAML.
• eslint-plugin-json-schema-validator ... ESLint plugin that validates data using JSON Schema Validator.
• jsonc-eslint-parser ... JSON, JSONC and JSON5 parser for use with ESLint plugins.
• yaml-eslint-parser ... YAML parser for use with ESLint plugins.
• toml-eslint-parser ... TOML parser for use with ESLint plugins.

License

See the LICENSE file for license rights and limitations (MIT).