Registry / devops / prettier-plugin-toml

prettier-plugin-toml

library2.0.6jsnpmunverified

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.

devops

npm install prettier-plugin-toml

github ↗package ↗

INSTALL

IMPORT

SIG · PRETTIER-PLUGIN-TO

prettier-plugin-toml

devopsjavascriptv2.0.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

prettier-plugin-toml

✓ import {} from 'prettier-plugin-toml'

✗ require('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

✓ import type { PrettierOptions } from 'prettier-plugin-toml'

✗ const PrettierOptions = require('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

✓ import prettierPluginToml from 'prettier-plugin-toml'

✗ import * as 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.

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

Debug

Known issues

breakingPrettier 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.

affects: >=2.0.0

deprecatedNamed 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.

affects: >=2.0.6

gotchaThe 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.

affects: all

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

fix

Upgrade Node to version 16.0.0 or later.

affects: >=2.0.0

gotchaOptions 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.

affects: all

gotchaThe 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.

affects: all

gotchaThe '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.

affects: all

Errors

Common errors & fixes

Cannot find module 'prettier-plugin-toml'

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.

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

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.

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

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+.

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

The file is not valid TOML according to taplo.

fix

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

Upgrade

Version history

2.0.6latest on npm

Audit

Dependencies

prettierrequiredpeer dependency required to function as a Prettier plugin

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/un-ts/prettier ↗

packagehttps://www.npmjs.com/package/prettier-plugin-toml ↗