prettier-plugin-toml weekly downloads statistics

prettier-plugin-toml

An opinionated toml formatter plugin for [Prettier][]

Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing, taking various rules into account.

This plugin adds support for toml through [tombi][].

Notice

This plugin is still under development, its printer just wraps [tombi][]'s default printer. Of course it should just work, but may not match [prettier][]'s format sometimes.

Requirements

prettier-plugin-toml is an evergreen module. 🌲 This module requires an LTS Node version (v20.0.0+).

Install

Using npm:

# npm
npm i -D prettier prettier-plugin-toml

# yarn
yarn add -D prettier prettier-plugin-toml

Usage

Once installed, Prettier plugins must be added to .prettierrc:

{
  "plugins": ["prettier-plugin-toml"]
}

Then:

# npx
npx prettier --write foo.toml

# yarn
yarn prettier --write foo.toml

Configuration

Besides the options below, this plugin reads [tombi][]'s own configuration, following its [search priority][tombi-config]. Discovery and merging are delegated to tombit, which performs the search in Rust:

1. Project — for each directory from the formatted file's directory up to the filesystem root: .tombi.toml, tombi.toml, .config/tombi.toml, then [tool.tombi] in pyproject.toml.
2. User — $XDG_CONFIG_HOME/tombi/config.toml, ~/.config/tombi/config.toml, plus the platform specific ~/Library/Application Support/tombi/config.toml (macOS) or %APPDATA%\tombi\config.toml (Windows).
3. System — /etc/tombi/config.toml.

The rules are resolved in ascending priority, each step overriding the previous one:

1. The discovered configuration's base rules, including the plugin options the user did not set.
2. Prettier's core options (printWidth, tabWidth, useTabs, singleQuote, bracketSpacing) and any plugin option the user explicitly sets, passed as overrideConfig.
3. The discovered configuration's per-file [[overrides]], applied by Tombi last.

Prettier's core options are always resolved, so they win over the discovered base rules (a matching [[overrides]] can still override them, because Tombi applies overrides last): a tombi.toml line-width that differs from Prettier's printWidth does not change this plugin's output. If you also use the tombi CLI or the VS Code extension, set line-width in tombi.toml to the same value as printWidth so both produce the same output — with no configuration at all, Prettier defaults to 80 while tombi has no line width limit.

The plugin's own options have no defaults: when they are not set, the discovered configuration (or Tombi's default) decides, except stringQuoteStyle and inlineTableBraceSpaceWidth, which derive from Prettier's singleQuote/bracketSpacing. toml-version follows the same rule because it decides how the source is parsed.

Notes

• Tombi's schema lookup is always disabled, so formatting stays offline and deterministic.
• Resolved configurations are cached and invalidated when the configuration file or its directory changes, so edits apply without restarting the process.

Parser Options

[prettier][]'s own core options are inherited and mapped to their tombi counterparts where they exist:

• printWidth → line-width
• tabWidth → indent-width
• useTabs → indent-style
• singleQuote → string-quote-style
• bracketSpacing → inline-table-brace-space-width

endOfLine is handled by [prettier][] itself. All of tombi's other format rules are exposed as toml options. They have no defaults: setting one overrides the discovered configuration, while leaving it unset lets tombi.toml (or Tombi's own default) decide — except stringQuoteStyle and inlineTableBraceSpaceWidth, which derive from the core options above.…