{"id":20444,"library":"prettier-plugin-toml","title":"prettier-plugin-toml","description":"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.","status":"active","version":"2.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/un-ts/prettier","tags":["javascript","toml","plugin","prettier","prettier-plugin","typescript"],"install":[{"cmd":"npm install prettier-plugin-toml","lang":"bash","label":"npm"},{"cmd":"yarn add prettier-plugin-toml","lang":"bash","label":"yarn"},{"cmd":"pnpm add prettier-plugin-toml","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required to function as a Prettier plugin","package":"prettier","optional":false}],"imports":[{"note":"The plugin is used as a Prettier plugin, not imported directly. It exports nothing, but must be specified in Prettier config's plugins array.","wrong":"require('prettier-plugin-toml')","symbol":"prettier-plugin-toml","correct":"import {} from 'prettier-plugin-toml'"},{"note":"TypeScript users can import the options type for type-checking. Note: PrettierOptions is exported as a named type, not a value.","wrong":"const PrettierOptions = require('prettier-plugin-toml')","symbol":"PrettierOptions","correct":"import type { PrettierOptions } from 'prettier-plugin-toml'"},{"note":"The plugin has a default export (the plugin object) for programmatic use. Avoid namespace import as it may break CommonJS interop.","wrong":"import * as prettierPluginToml from 'prettier-plugin-toml'","symbol":"default","correct":"import prettierPluginToml from 'prettier-plugin-toml'"}],"quickstart":{"code":"// Install: npm i -D prettier prettier-plugin-toml\n// .prettierrc (or prettier.config.js):\nmodule.exports = {\n  plugins: ['prettier-plugin-toml'],\n  // Optional configuration:\n  alignEntries: true,\n  reorderKeys: false,\n  indentTables: true,\n};\n\n// Then format:\n// npx prettier --write your-file.toml","lang":"javascript","description":"Demonstrates installation, plugin configuration in .prettierrc, and execution via CLI."},"warnings":[{"fix":"Upgrade Prettier to v3 (npm i -D prettier@latest). Note that plugin options may differ from v2.","message":"Prettier v3 dropped support for plugins using the old API. This plugin requires prettier@^3.0.3.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use default import (import p from 'prettier-plugin-toml') or specify the plugin in Prettier config's plugins array by string name.","message":"Named exports for CommonJS were removed in v2.0.6. Previously, some users used CommonJS require with named imports; that now breaks.","severity":"deprecated","affected_versions":">=2.0.6"},{"fix":"Adjust plugin-specific options (indentTables, alignEntries, etc.) to better match your project's Prettier configuration.","message":"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).","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade Node to version 16.0.0 or later.","message":"Node 16+ requirement. Older Node versions (e.g., 14) will not work.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Review the option documentation and test formatting on sample TOML files to ensure desired behavior.","message":"Options like 'compactArrays' and 'arrayAutoExpand' may conflict. By default, arrays are auto-expanded/collapsed; setting both true can cause confusion.","severity":"gotcha","affected_versions":"all"},{"fix":"Set compactInlineTables: true in Prettier options if desired.","message":"The plugin does not format inline tables as compact by default; 'compactInlineTables' is false. Users expecting minimal whitespace may be surprised.","severity":"gotcha","affected_versions":"all"},{"fix":"Set reorderKeys: false unless you intentionally want key sorting.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run npm i -D prettier-plugin-toml in the project root and ensure node_modules contains it.","cause":"Plugin not installed or not in node_modules, or Prettier can't locate it (e.g., global install mismatch).","error":"Cannot find module 'prettier-plugin-toml'"},{"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.","cause":"Plugin loaded but does not export a parsers object (e.g., wrong import style in older v1).","error":"TypeError: Cannot read properties of undefined (reading 'parsers')"},{"fix":"Check that prettier-plugin-toml is listed in the .prettierrc 'plugins' array and that Prettier is v3+.","cause":"The plugin's parser is not recognized; likely a version mismatch or incorrect plugin registration.","error":"prettier-plugin-toml: Unknown parser option 'toml'"},{"fix":"Validate the TOML syntax using a linter (e.g., toml-lint) before running Prettier.","cause":"The file is not valid TOML according to taplo.","error":"SyntaxError: Unexpected token (1:1) while parsing TOML file"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}