Formatting — tcm-ts

14. Formatting

tcm formats with oxfmt, with nothing to install or configure. Formatting never changes a hash: a definition's hash has no whitespace, layout, quotes or trailing commas in it. So tcm formats freely, without touching identity, history or what depends on what.

  • What's saved is formatted. tcm add and tcm update store each definition as oxfmt formats it, so tcm view, tcm edit, pages and generated modules show one style, whoever wrote the code and however. The scratch file itself is left as you wrote it. A mirrored codebase is the exception: its code reads as its files do, so it's stored as written.
  • In VS Code, a scratch file is formatted as it's saved, and by Format Document. (Other editors: the language server answers textDocument/formatting and willSaveWaitUntil.)
  • tcm fmt [namespace] reformats what's already stored, after a style change or an oxfmt upgrade. No hash changes and nothing is re-derived: the new layout is this branch's, an entry in its history like a comment change (history).
$ tcm fmt
  ~ lib.greet
  ~ lib.shout
reformatted 2 definition(s); no hashes changed

Every formatted text is analyzed again before it's kept, and kept only if each definition hashes exactly as before. A formatter can't change what code means: tcm keeps the text as it was, and says so. oxfmt does change one thing: breaking a long line of JSX text before an expression, it puts in a {" "}, which gives React other children ("a ", x against "a", " ", x). A definition that would change so is saved as written (tcm add says which), and the rest of its file formatted, what uses it too.

14.1 fmt.config

A definition at fmt.config holds oxfmt's options: Prettier's (printWidth, singleQuote, semi, trailingComma, …; the full list).

// tcm: namespace fmt
export const config = { singleQuote: true, semi: false, printWidth: 100 };

Changing it changes how new code is saved; tcm fmt restyles what's already there.

oxfmt comes with tcm, at the version tcm was tested with: nothing to install. tcm upgrade oxfmt@<range> chooses another for the codebase, installed in its cache and pinned in the lock like any package (tcm packages).

built from c482a14e