Serialization 02 📄 Tooling, Linter Integration, and Formatting (yamlfmt, prettier, taplo)
Formatting tools for YAML and TOML are not interchangeable. The ecosystem has converged on a division of labor: yamlfmt and Prettier handle YAML, taplo handles TOML, and Prettier’s TOML support is a plugin that wraps taplo rather than a native implementation. Choosing the wrong tool produces inconsistent formatting, silent failures in CI, and configuration that drifts between editors. This chapter covers the three tools, their installation and usage, and the integration patterns that keep formatting enforced across a team.
The sections that follow walk through yamlfmt and its configuration options, Prettier’s YAML support and its limits, and taplo as the TOML-specific tool. Each section pairs the command with the CI pattern that makes formatting enforceable rather than advisory.
Key point: Use yamlfmt or Prettier for YAML and taplo for TOML; Prettier’s TOML support depends on a plugin that wraps taplo, so taplo is the direct dependency in either case.
Why formatting tools exist
The consistency problem. A YAML file edited by three developers will contain three indentation styles, three quoting conventions, and three opinions about whether sequences should be indented under their keys. The parser does not care; the reviewer does. A formatter removes the argument by making every file look the same, and a CI check makes the consistency enforceable rather than aspirational.
The TOML tooling gap problem. Prettier’s documentation lists YAML as a supported language, but TOML is not in Prettier’s native language set . The prettier-plugin-toml package exists, but its implementation delegates to taplo rather than parsing TOML itself . This means adding TOML to a Prettier setup adds taplo as a transitive dependency, and the formatting behavior is taplo‘s behavior regardless of the Prettier configuration.
The configuration surface problem. yamlfmt‘s defaults are opinionated in ways that surprise first-time users. The tool indents sequence items under their parent key by default, which is valid YAML but differs from the common style of leaving sequence items at the same indentation as the key. The indentless_arrays option changes this, and the retain_line_breaks option prevents the formatter from collapsing intentional blank lines . A formatter that fights the author’s style will be disabled rather than adopted.
a. yamlfmt: installation, usage, and configuration
yamlfmt is a Go-based YAML formatter maintained by Google (though the repository notes it is not officially supported by Google and is maintained by a single contributor in spare time) . It installs as a single binary with no runtime dependencies.
# Install via Go
go install github.com/google/yamlfmt/cmd/yamlfmt@latest
# Format specific files (writes to stdout)
yamlfmt file1.yaml file2.yaml
# Format in place
yamlfmt -w file1.yaml file2.yaml
# Format a directory recursively
yamlfmt .The tool reads configuration from a .yamlfmt file in the working directory, a path passed with --conf, or a global config path. The two options that matter for most projects are indentless_arrays and retain_line_breaks .
# .yamlfmt
formatter:
indentless_arrays: true
retain_line_breaks: true
scan_folded_as_literal: trueindentless_arrays: true stops the formatter from adding two spaces before sequence items under a mapping key. retain_line_breaks: true preserves blank lines the author inserted for readability. scan_folded_as_literal: true prevents the formatter from collapsing > folded blocks into single lines, which is destructive for HTML or long text blocks .
For CI, yamlfmt provides a -lint flag that exits non-zero if any file would be reformatted, and -quiet to reduce output to the file paths that differ .
# CI check: fail if formatting differs
yamlfmt -lint -quiet .b. Prettier: YAML support and the TOML gap
Prettier formats YAML natively. Its documentation lists YAML as a supported language, and the formatter applies consistent indentation, quote style, and line wrapping to .yaml and .yml files . For teams already using Prettier for JavaScript, TypeScript, and JSON, adding YAML is a configuration change, not a new dependency.
# Format YAML with Prettier
npx prettier --write "**/*.{yaml,yml}"
# Check without writing (CI)
npx prettier --check "**/*.{yaml,yml}"The limit is TOML. Prettier does not natively support TOML . The prettier-plugin-toml package provides TOML formatting, but it is a wrapper around taplo . A project that wants Prettier to handle both formats must install the plugin, and the plugin’s behavior is taplo‘s behavior, not Prettier’s. The practical consequence is that taplo is the TOML formatter either way; the plugin only changes how it is invoked.
c. taplo: the TOML toolkit
taplo is a TOML validator, formatter, and language server written in Rust. It is the reference implementation for TOML formatting in the JavaScript ecosystem because the Prettier plugin delegates to it . It installs via Cargo, npm, or Yarn.
# Install via npm
npm install -g @taplo/cli
# Format all TOML files in the project
npx @taplo/cli fmt
# Check formatting without writing (CI)
npx @taplo/cli fmt --checktaplo also provides a lint subcommand for validating TOML documents beyond formatting, and it supports schema validation for common configuration files like Cargo.toml and pyproject.toml . The configuration file is taplo.toml, and the formatter options include align_comments, which aligns inline comments across a block .
For pre-commit integration, taplo has an unofficial hook maintained by the community (ComPWA/taplo-pre-commit), because the main project has not published an official pre-commit hook . A project that uses pre-commit can either add the unofficial hook or run taplo fmt --check as a local hook.
Complete Example Session
# ============================================
# PART 1: PROJECT STRUCTURE
# ============================================
# project/
# .yamlfmt # yamlfmt configuration
# .prettierrc # Prettier configuration
# taplo.toml # taplo configuration
# config.yaml
# pyproject.toml
# ============================================
# PART 2: YAMLFMT CONFIGURATION
# ============================================
# .yamlfmt
formatter:
indentless_arrays: true # no extra indent for sequences
retain_line_breaks: true # keep intentional blank lines
scan_folded_as_literal: true # don't collapse > blocks
# ============================================
# PART 3: PRETTIER CONFIGURATION (YAML)
# ============================================
# .prettierrc
# {
# "tabWidth": 2,
# "singleQuote": true
# }
# ============================================
# PART 4: TAPLO CONFIGURATION
# ============================================
# taplo.toml
# [formatting]
# align_comments = true
# ============================================
# PART 5: CI COMMANDS
# ============================================
# YAML with yamlfmt
# yamlfmt -lint -quiet .
# YAML with Prettier
# npx prettier --check "**/*.{yaml,yml}"
# TOML with taplo
# npx @taplo/cli fmt --checkThe parts covered the project structure, yamlfmt configuration options, Prettier YAML configuration, taplo configuration, and the CI check commands for each tool.
Quick Reference
Tool Comparison
| Tool | Formats | Installation | CI Flag |
|---|---|---|---|
yamlfmt | YAML | go install or binary | -lint |
| Prettier | YAML (native), TOML (plugin) | npx prettier | --check |
taplo | TOML | npm install -g @taplo/cli | fmt --check |
yamlfmt Configuration Options
| Option | Default | Effect |
|---|---|---|
indentless_arrays | false | No extra indent for sequence items |
retain_line_breaks | false | Preserve blank lines |
scan_folded_as_literal | false | Don’t collapse > blocks |
Prettier TOML Dependency
| Aspect | Detail |
|---|---|
| Native TOML | No |
| Plugin | prettier-plugin-toml |
| Underlying engine | taplo |
| Practical implication | taplo is always the TOML formatter |
Best Practices
✅ Do This:
# Configure yamlfmt before adopting it
# .yamlfmt with indentless_arrays and retain_line_breaks # ✅
# Use taplo directly for TOML
npx @taplo/cli fmt --check # ✅
# Run formatting checks in CI
yamlfmt -lint -quiet . # ✅
# Use the same tool locally and in CI
# (avoid editor-specific formatting that CI rejects) # ✅❌ Don’t Do This:
# Assume Prettier handles TOML natively
npx prettier --check "**/*.toml" # ❌ (no native support)
# Use yamlfmt defaults without testing on existing files
yamlfmt -w . # ❌ (may reindent sequences)
# Run formatter in CI without checking locally first
yamlfmt . # no -lint, no -w # ❌ (output only)Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Sequence items reindented unexpectedly | yamlfmt default behavior | Set indentless_arrays: true |
| Folded block collapsed | Default scan_folded_as_literal: false | Set to true |
| Prettier TOML check fails | No native TOML support | Use taplo or the plugin |
| CI passes locally but fails remotely | Different tool versions | Pin versions in CI config |
| Blank lines removed | retain_line_breaks not set | Set to true |
Real-World Examples
1. Install yamlfmt
go install github.com/google/yamlfmt/cmd/yamlfmt@latest2. Format YAML in place
yamlfmt -w config.yaml3. yamlfmt CI check
yamlfmt -lint -quiet .4. Prettier YAML check
npx prettier --check "**/*.{yaml,yml}"5. Install taplo
npm install -g @taplo/cli6. taplo format check
npx @taplo/cli fmt --check7. yamlfmt config file
formatter:
indentless_arrays: true8. taplo config file
[formatting]
align_comments = true9. Prettier with TOML plugin
npm install -D prettier-plugin-toml10. Docker yamlfmt
docker run -v "$(pwd):/project" ghcr.io/google/yamlfmt:latest -lint .Visual
The Tool Landscape
┌─────────────────────────────────────────────────────────┐
│ FORMATTERS BY FORMAT │
│ │
│ YAML │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ yamlfmt │ │ Prettier │ │
│ │ (Go, binary) │ │ (native) │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ TOML │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ taplo │ │ Prettier │ │
│ │ (Rust) │ │ + plugin │ │
│ └──────────────┘ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ taplo engine │ │
│ └──────────────┘ │
│ │
│ Prettier's TOML is taplo under a plugin wrapper │
└─────────────────────────────────────────────────────────┘yamlfmt’s Default Behavior
┌─────────────────────────────────────────────────────────┐
│ DEFAULT (indentless_arrays: false) │
│ │
│ key: │
│ - item1 ◄── extra indent added │
│ - item2 │
│ │
│ CONFIGURED (indentless_arrays: true) │
│ │
│ key: │
│ - item1 ◄── same column as key │
│ - item2 │
│ │
│ Both valid; the option matches common style │
└─────────────────────────────────────────────────────────┘CI Integration Flow
┌─────────────────────────────────────────────────────────┐
│ CI FORMATTING PIPELINE │
│ │
│ Developer commits │
│ │ │
│ ▼ │
│ CI runs: │
│ ┌──────────────────────────────────────────┐ │
│ │ yamlfmt -lint -quiet . │ │
│ │ npx @taplo/cli fmt --check │ │
│ └──────────────────────────────────────────┘ │
│ │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ PASS FAIL │
│ │ │ │
│ ▼ ▼ │
│ Merge Developer runs formatter │
│ locally, commits fix │
└─────────────────────────────────────────────────────────┘yamlfmt Folded Block Behavior
┌─────────────────────────────────────────────────────────┐
│ scan_folded_as_literal: false (default) │
│ │
│ description: > │
│ <table> │
│ <tr><td>1</td></tr> │
│ </table> │
│ │ │
│ ▼ │
│ Collapsed to one line (destructive) │
│ │
│ scan_folded_as_literal: true │
│ │ │
│ ▼ │
│ Line breaks preserved │
└─────────────────────────────────────────────────────────┘Summary
| Item | Value |
|---|---|
| YAML formatter (Go) | yamlfmt |
| YAML formatter (JS) | Prettier (native) |
| TOML formatter | taplo |
| Prettier TOML | Plugin wrapping taplo |
| yamlfmt CI flag | -lint |
| taplo CI flag | fmt --check |
| yamlfmt key option | indentless_arrays |
| taplo config file | taplo.toml |
Key takeaways:
- The formatter ecosystem is split by format.
yamlfmtand Prettier handle YAML;taplohandles TOML. Prettier’s TOML support is a plugin that delegates totaplo, sotaplois the TOML engine regardless of how it is invoked . yamlfmt‘s defaults need configuration for most projects. The default sequence indentation and line-break handling differ from common style;indentless_arraysandretain_line_breaksalign the formatter with the file .- Prettier is the right choice when the project already uses it. Adding YAML formatting to an existing Prettier setup costs a configuration change; adding TOML requires the plugin and therefore
taplo. - CI enforcement requires a check flag.
yamlfmt -lintandtaplo fmt --checkexit non-zero when formatting differs, turning style into a gate rather than a suggestion . - Pin versions across local and CI. A formatter that changed between versions will produce diffs that local development cannot reproduce, and the CI failure will be unexplainable without the version lock.
Remember: Formatting tools are only useful when they are enforced. yamlfmt and taplo both provide check flags for CI; Prettier provides --check. The configuration is secondary to the gate: a project that runs the formatter in CI with a pinned version will converge on consistency, while a project that only documents “run the formatter” will not. Choose the tool for the format, configure the options that match the team’s style, and add the check to CI before adding the formatter to the editor.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!