Prettier Rust

Why Prettier?

What usually happens once people start using Prettier is that they realize how much time and mental energy they actually spend formatting their code. With Prettier editor integration, you can just press the Format Document key binding and poof, the code is formatted. This is an eye-opening experience if anything.

• Beautiful, uniform and consistent — Prettier is strongly opinionated, it has zero style options.
• Life-changing Editor Integration — Prettier can format WIP code before it can compile (e.g. missing annotations)
• Stop wasting time on formalities — Prettier autocorrects bad syntax (e.g. missing semicolons, blocks, parentheses...)

const LEET = 1337
/// My WIP code draft
#![feature(crate_visibility_modifier)]
async crate fn foo(arg) {
  arg.0 *= 3.14 + LEET & 1337
  arg.1(|b, c| -> T &c).await
}

const LEET = 1337;
#![feature(crate_visibility_modifier)]
/// My WIP code draft
crate async fn foo(arg) {
    arg.0 *= (3.14 + LEET) & 1337;
    (arg.1)(|b, c| -> T { &c }).await
}

Configuration

https://prettier.io/docs/en/configuration

// .prettierrc.json
{
  "useTabs": false,
  "tabWidth": 4,
  "printWidth": 100,
  "endOfLine": "lf",

  // -- Not supported yet --
  // "trailingComma": "es5",
  // "embeddedLanguageFormatting": "auto",

  // Example override
  "overrides": { "files": ["tests/*.rs"], "options": { "printWidth": 80 } }
}

# .prettierrc.toml

useTabs = false
tabWidth = 4
printWidth = 100
endOfLine = "lf"

# -- Not supported yet --
# trailingComma = "es5"
# embeddedLanguageFormatting = "auto"

# Example override
overrides = [
  { files = ["tests/*.rs"], options = { printWidth = 80 } }
]

How to ignore things

• Add // prettier-ignore or #[rustfmt::skip] above it
• Add #![rustfmt::skip] inside blocks or files
• Create a .prettierignore file to glob-match files, like .gitignore

How are macros formatted?

• Curlies !{} format like blocks, ![] and !() like comma-separated expressions
• Formatting inside macro invocations is more conservative, since macros can be token-sensitive
• Popular/built-in macros with original syntax rules get custom formatting (e.g. matches!, if_chains!...)
• Macro Declarations are only partially formatted (the transformed part isn't yet, but could be in the future)
• Macros that can't be formatted are silently ignored

Are nightly features supported?

Yes! Prettier Rust formats most nightly features. Support depends on jinx-rust.

Editor integration

• Recommended Extension Standalone

  Easy install + auto-updates

  • VSCode | Search and install Prettier - Code formatter (Rust) [direct link]

  • Request your favorite editor: [file an issue]

• Alternative Core Extension Plugin

  Requires NodeJS + Prettier Extension (built-in Jetbrains IDEs)

  npm install --global prettier-plugin-rust prettier

  Restart IDE after installing.
  To update (manual only!!): npm upgrade --global prettier-plugin-rust prettier
  To check installed version: npm ls -g --depth=0 prettier-plugin-rust prettier
  To check latest version: npm info prettier-plugin-rust version

Project integration

• Command line

  Requires NodeJS

  • Install prettier and prettier-plugin-rust globally

    npm install --global prettier-plugin-rust prettier

  • Use the prettier CLI to format rust files. E.g. run:

    prettier --write **/*.rs

• NodeJS package

  Requires NodeJS

  • Install prettier and prettier-plugin-rust in the project

    npm install --save-dev prettier-plugin-rust prettier

  • Link to the plugin's location in your prettier config:

    "plugins": ["./node_modules/prettier-plugin-rust"]

  • Use the prettier CLI to format rust files. E.g. run:

    npx prettier --write **/*.rs

• Rust crate

  No crate yet. Above options are available in the meantime.

Q&A

• Why would I use this and not the established cargo fmt ?

  It mostly comes down to the Editor Integration. — With Prettier Rust, you have the ability to hit the Format Document keybind on incomplete code and everything fits right into place. Again reiterating on what was said in the introduction, but this is actually life-changing. Just try it out, 1-click install the extension, write a few lines and hit the keybind.

  There's only little difference in terms of how code is printed, so adopting Prettier Rust won't drastically change a codebase. Prettier's only downside against Rustfmt is its troublesome integration into the Rust ecosystem. Fortunately it's only a matter of time before it gets resolved.

  See also:

  • Prettier Rust does not have style options.
  • Prettier Rust produces slightly more readable code (e.g. parenthesis around compound bin ops)
  • Prettier Rust supports more things by default (nightly features, macros, ...)
  • Prettier consistently prints code in the same way, whereas rustfmt preserves arbitrary style at places
  • Prettier is available for many languages (e.g. markdown, html, typescript, java, python, ruby...)
  • Prettier supports language embeds. It formats rust code blocks in non-rust files (e.g. markdown), and conversely formats supported languages within rust doc comments.

• How can Prettier Rust format files that the Rust Compiler cannot parse?

  Prettier Rust is based on jinx-rust, a Rust Parser specially built for Rust Tooling. Learn more about jinx-rust here.

• How does Prettier Rust compare to Prettier Typescript?

  Prettier Rust is essentially a port of Prettier Typescript. The Rust plugin barely introduces style opinions on its own.