prettier-plugin-toml

2.0.6 verified Sat Apr 25 auth: no javascript

A Prettier plugin for formatting TOML files, powered by taplo. Current stable version is 2.0.6 (released December 2024, part of the un-ts monorepo with frequent releases). It supports Prettier v3 and requires Node >=16. Differentiators: aligns with Prettier's opinionated style, offers many formatting options (alignEntries, reorderKeys, compactArrays, etc.), ships TypeScript types, and is actively maintained. Unlike standalone TOML formatters, this integrates as a Prettier plugin, allowing consistent formatting across multiple languages.

Common errors

error Cannot find module 'prettier-plugin-toml' ↓

cause Plugin not installed or not in node_modules, or Prettier can't locate it (e.g., global install mismatch).

fix

Run npm i -D prettier-plugin-toml in the project root and ensure node_modules contains it.

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

cause Plugin loaded but does not export a parsers object (e.g., wrong import style in older v1).

fix

Ensure you use prettier-plugin-toml v2+ and indicate plugin in .prettierrc as 'prettier-plugin-toml', not as a require or import in the config.

error prettier-plugin-toml: Unknown parser option 'toml' ↓

cause The plugin's parser is not recognized; likely a version mismatch or incorrect plugin registration.

fix

Check that prettier-plugin-toml is listed in the .prettierrc 'plugins' array and that Prettier is v3+.

error SyntaxError: Unexpected token (1:1) while parsing TOML file ↓

cause The file is not valid TOML according to taplo.

fix

Validate the TOML syntax using a linter (e.g., toml-lint) before running Prettier.

Warnings

breaking Prettier v3 dropped support for plugins using the old API. This plugin requires prettier@^3.0.3. ↓

fix Upgrade Prettier to v3 (npm i -D prettier@latest). Note that plugin options may differ from v2.

deprecated Named exports for CommonJS were removed in v2.0.6. Previously, some users used CommonJS require with named imports; that now breaks. ↓

fix Use default import (import p from 'prettier-plugin-toml') or specify the plugin in Prettier config's plugins array by string name.

gotcha The plugin's formatting behavior is based on taplo's default printer and may not perfectly match Prettier's style for other languages (e.g., indentation, line width). ↓

fix Adjust plugin-specific options (indentTables, alignEntries, etc.) to better match your project's Prettier configuration.

gotcha Node 16+ requirement. Older Node versions (e.g., 14) will not work. ↓

fix Upgrade Node to version 16.0.0 or later.

gotcha Options like 'compactArrays' and 'arrayAutoExpand' may conflict. By default, arrays are auto-expanded/collapsed; setting both true can cause confusion. ↓

fix Review the option documentation and test formatting on sample TOML files to ensure desired behavior.

gotcha The plugin does not format inline tables as compact by default; 'compactInlineTables' is false. Users expecting minimal whitespace may be surprised. ↓

fix Set compactInlineTables: true in Prettier options if desired.

gotcha The 'reorderKeys' option alphabetically reorders keys. This can break TOML files that rely on key order for semantics (e.g., Cargo.toml's dependencies). Use with caution. ↓

fix Set reorderKeys: false unless you intentionally want key sorting.

Install

npm install prettier-plugin-toml

yarn add prettier-plugin-toml

pnpm add prettier-plugin-toml

Imports

prettier-plugin-toml
wrong
```
require('prettier-plugin-toml')
```
correct
```
import {} from 'prettier-plugin-toml'
```
The plugin is used as a Prettier plugin, not imported directly. It exports nothing, but must be specified in Prettier config's plugins array.
PrettierOptions
wrong
```
const PrettierOptions = require('prettier-plugin-toml')
```
correct
```
import type { PrettierOptions } from 'prettier-plugin-toml'
```
TypeScript users can import the options type for type-checking. Note: PrettierOptions is exported as a named type, not a value.
default
wrong
```
import * as prettierPluginToml from 'prettier-plugin-toml'
```
correct
```
import prettierPluginToml from 'prettier-plugin-toml'
```
The plugin has a default export (the plugin object) for programmatic use. Avoid namespace import as it may break CommonJS interop.

Quickstart

Demonstrates installation, plugin configuration in .prettierrc, and execution via CLI.

// Install: npm i -D prettier prettier-plugin-toml
// .prettierrc (or prettier.config.js):
module.exports = {
  plugins: ['prettier-plugin-toml'],
  // Optional configuration:
  alignEntries: true,
  reorderKeys: false,
  indentTables: true,
};

// Then format:
// npx prettier --write your-file.toml