A better Prettier CLI and config file

[lydell]

I would like to present a completely new take on Prettier’s CLI. Let’s restart from scratch. This isn’t a complete spec or even fully thought through yet. But I’ve been having this on my mind for a long time and wanted to get something out there for discussion.

Goal: Make it easy to do the right thing, and hard to do the wrong thing. Simplify everything! No magic! More explicitness! But still easy to use.

This is a bad thing:

{
    "scripts": {
        "prettier": "prettier --single-quote --write \"src/**/*.{js,css}\" \"docs/**/*.md\""
    }
}

Why?

• Editors won’t know which options to use, and which files to work on.
• How do you run that with --check for CI?
• What about git hooks or lint-staged?
• What if you want to run prettier on a couple of files from the command line for a one-off task?
• It is annoying to write those globs.

Globs and --foo-style options for formatting are anti-patterns. I suggest we get rid of them!

Instead, imagine having this:

{
    "scripts": {
        "prettier": "prettier format",
        "prettier:check": "prettier check"
    }
}

Nice, huh?

prettier

A subcommand is required. Print help.

prettier format [PATH]...

Format files and overwrite them on disk. Like today’s --write, more or less.

Passing no paths is a shortcut for prettier format ..

If a PATH points to a file, that file is formatted. If the file is ignored a note about that is printed. (We could have a --force flag to override.) If the file type isn’t something that Prettier handles, an error is printed.

If a PATH points to a directory, Prettier will automatically find all files to work deeply and format them. Which files exactly? More on that later.

Regarding the output, I think we can take inspiration from black. Let’s be minimal and print stuff like “✨All files formatted with Prettier!” and “✨Formatted 5 files.”

Who will use this?

• People who for whatever reason don’t run Prettier in their editor.
• After adding Prettier to a project, or changing an option.
• After a CI failure, you can run prettier format to fix everything.
• After a big find-and-replace refactor in src/components you can run prettier format src/components to fix formatting (without having to run on the entire project).
• git hooks.
• lint-staged (it passes absolute paths to tools).

Note: I think we should ditch built-in support for globs altogether. They’re not needed! If you need globs for a one-off command, then it’s up to you to get a good shell for yourself and use its globs.

prettier check [PATH]...

Like prettier format, but only checks if files are already formatted or not. Like today’s --check.

Who will use this?

• CI.
• Git hooks and lint-staged could alternatively use this instead of prettier format.

prettier stdio FILE

Run Prettier over stdin and stdout.

The FILE argument is required, so that Prettier knows what file type the content is, and if the file should be ignored or not.

If FILE exists, prettier stdio some/file.js is a shortcut for prettier stdio some/file.js < some/file.js.

If FILE is ignored, or isn’t supported by Prettier we should use exit codes and stuff to let the caller know.

Who will use this?

• vim-prettier, and other editors that shell out to format.
• People who occasionally use Prettier as a unix tool. prettier stdio tmp/index.min.js | grep foo.

prettier.json

Prettier advocates for few options, but our configuration is super complicated! I think we should take a step back and re-think here.

Let’s have one config file to rule them all – prettier.json. A prettier.json should be required for Prettier to run – this makes Prettier opt-in. For every file Prettier formats, there must be a prettier.json next to it or up the file tree. Only the first found prettier.json is used – there’s no cascade.

Making Prettier opt-in would make it super clear that a project is using Prettier. For example, it would help editor integrations. I hate it when my editor changes an entire file on save when I just wanted to make a quick edit in somebody else’s non-Prettier project.

A --force flag could be used for one-off formatting of files with no prettier.json. That would use the default options. --config ~/foo/prettier.json could use a specified one.

prettier.json should specify:

• Options. Global ones, as well as options per language. Not per file. Per language. This allows having double quotes in HTML, but single quotes in JS – even inside <script> tags in HTML. Some options can only be set per language and not globally – such as which parser to use.
• File extension mappings. You should be able to map .foo to be handled as JSON, for example. When running prettier format ., Prettier looks for all files with known file extensions.
• What files to ignore. An array of gitignore-style patterns. And the possibility to link to ignore files, such as .gitignore and .eslintignore. Or .prettierignore or .whateverignore if you want! Explicit and no magic. Ignore *.html to opt out of HTML formatting, for example.
• Anything you’d ever need to configure, so you don’t need CLI flags. prettier.json should be the source of truth so that other tools know what to do.

We should continue supporting "@company/prettier-config" and similar to load the config from an npm package.

prettier init could be an interactive command to help create a prettier.json. For most people, it will just contain {} (an empty object), though. For example, it could ask which languages your are/aren’t interested in formatting (based on what files we find on disk) and help set up ignore patterns. And we could detect .gitignore and .eslintignore and ask if we should link to them.

Not sure if we need overrides.

Some options could take a "editorconfig" as a value. If so, we’ll look for .editorconfig to figure out what value to use. No magic!

What about YAML or TOML or whatever instead of JSON? Keep it simple, I’d say! prettier.json should ideally be so short and simple that we don’t need a fancy language to write it.

{
  "useTabs": true,
  "javascript": {
    "singleQuote": true,
    "parser": "babel-flow"
  },
  "fileExtensions": {
    ".foo": "javascript"
  },
  "ignore": [
    "*.html",
    "/legacy/",
    { "include": "./.gitignore" },
    "!*.config.js"
  ]
}

Open questions

• --range-start, --range-end and --cursor-offset. Not sure how they fit in yet.
• --insert-pragma and --require-pragma. I’ve never used these myself so I’m not sure.
• --file-info and --support-info. Not sure these are going to be needed anymore.
• Many other little command line options...

[octogonz]

Prettier's CLI seems to be inspired by ESLint's CLI, which has the exact same problems. I suspect that it's confounded by a reality that nobody uses the CLI in real life. People generally invoke Prettier via an editor extension or a Git hook driver like lint-staged, pretty-quick, etc.

In #6280 when I tried to use the CLI to "fix all the files," I found that the .prettierignore file selection had major gaps. It overlooks that:

• The Git hook drivers implicitly filter out files that are not tracked by Git (i.e. essentially intersecting .prettierignore with .gitignore)
• The VS Code extension implicitly filters out files that a person wouldn't try to edit in their editor (which approximates .gitignore as well)

Whereas when you use the CLI to "fix all files," it becomes awkward to specify them. As you pointed out, the CLI glob is really only suitable for manually prettifying specific files (and probably it should bypass .prettierignore entirely). When I tried to use .prettierignore to accurately specify the same thing as .gitignore, its implementation turned out to have serious performance problems, essentially doing a brute-force crawl of all files. (See #6280 for details.)

How would you address this? Here's a few possible approaches:

• The Prettier CLI should integrate with Git and ignore untracked files; this would allow it to be a realistic alternative to lint-staged & co; OR
• We should normalize the idea that .prettierignore exactly specifies the file set that is intended to be prettified, perhaps duplicating or importing .gitignore rules; OR
• The Prettier CLI shouldn't pretend to select the right files; it should stupidly process whatever file paths its given, and leave file selection to some other shell command

[octogonz]

Making Prettier opt-in would make it super clear that a project is using Prettier. For example, it would help editor integrations. I hate it when my editor changes an entire file on save when I just wanted to make a quick edit in somebody else’s non-Prettier project.

+1

I'll mention that in a large monorepo, we generally prefer for each project to have its own local tooling config files. In most cases the config will be a single line that $extends from a boilerplate "@company/foo-config", with occasional extra options for certain projects. This makes it easier to move projects around between folders/monorepos without worrying about coordinating changes in a centralized config file. It also reduces the overhead for updates, since modifying a centralized file in a large monorepo typically requires extra approvals/signoffs that can slow people down.

At least, this was certainly the case for files like tsconfig.json, eslintrc.js, jest.config.js, etc. With TypeScript/ESLint we also had to worry about different projects using different versions of the tool/plugins, essentially requiring the tool to be invoked separately in each folder. The Prettier config /might/ avoid this concern, since migrating to a new Prettier release should require no human effort. So maybe Prettier's CLI can always be invoked once for an entire monorepo. I haven't used it enough to have a good sense of this yet.

Just something to think about in your design discussion.

[tunnckoCore]

Love the idea of explicitness. I'm always for that, for years.

@lydell: Making Prettier opt-in would make it super clear that a project is using Prettier. For example, it would help editor integrations. I hate it when my editor changes an entire file on save when I just wanted to make a quick edit in somebody else’s non-Prettier project.

There's requireConfig in vscode-prettier for that, I have it enabled exactly for such reasons and that the only option set in vscode prettier settings.

Why?

Not meaningful questions. All of this is handled and I don't see any problems with them.

It is annoying to write those globs.

Agreed. Prettier should allow executing without globs, since for example you have overrides which has globs already. Currently I'm doing prettier '**/*', overrides for what I want to be formatted and a prettierignore like

# Ignore everything!
*

# de-ignores: add here what you want to be committed

!*.*js*
!*.ts*
!*.md*
!*.y*ml

!**/src
!**/src/**

!**/test
!**/test/**

# re-ignores: add here what you want to be ignored again
test/tmp

test/fixture/file
test/fixture/http

A subcommand is required.

I like that requirement for subcommands.

Note: I think we should ditch built-in support for globs altogether.
... then it’s up to you to get a good shell for yourself and use its globs.

Totally against. Globs are the best thing. Better cross platformability, easier to control what to pass to tool (Prettier) and etc. Good example for "on top of globs" thing is glob-cache - run first time and cache, run second time and execute a handler hook (passed with full filepath) only if there is a diff between the actual file and the cache file.

Prettier advocates for few options, but our configuration is super complicated! I think we should take a step back and re-think here.

Agree. I'm already lost in options.

A prettier.json should be required for Prettier to run – this makes Prettier opt-in.

Not entirely agreeing with that. This can be accomplished with better defaults. For example, prettier.requireConfig: true to be a default one for vscode-prettier. From CLI, yea, require config. (And remove the require-pragma thingy)

For every file Prettier formats, there must be a prettier.json next to it or up the file tree. Only the first found prettier.json is used – there’s no cascade.

Agree. No shareable configs, no overrides and etc. ESLint has RFC#9 for that too - just single eslint.config.js, in our case prettier.config.js. But also, should of course be possible something like "prettier": "my-config" in package.json or "my-config" in prettier.json.

Per language

Agree 💯

File extension mappings.

Agree 💯

What files to ignore. An array of gitignore-style patterns.

Not entirely agree. Gitignore isn't the best thing, definitely. You clearly can see from above how I have duplicate lines just because the way gitignore works. Here the "file extension mappings" could help too. Just ignore everything by default, except those that are in mappings.

everything you want to configure, prettier.json is the single source of truth

👍

prettier init

👍 💯

Not sure if we need overrides

Yup, we don't.

Some options could take a "editorconfig" as a value. If so, we’ll look for .editorconfig to figure out what value to use. No magic!

Totally agree 💯

{ "include": "./.gitignore" },

Agree.

@octogonz file selection had major gaps. It overlooks that...

True

I'll mention that in a large monorepo, we generally prefer for each project to have its own local tooling config files.
This makes it easier to move projects around between folders/monorepos without worrying about coordinating changes in a centralized config file

True. I'm fan of that idea.

[lydell]

@tunnckoCore

There's requireConfig in vscode-prettier

Thanks! Didn’t know about that!

Note: I think we should ditch built-in support for globs altogether.
... then it’s up to you to get a good shell for yourself and use its globs.

Totally against. Globs are the best thing.

In what situation would you use globs with the CLI described in this issue?

[tunnckoCore]

In what situation would you use globs with the CLI described in this issue?

True. I can't think of now. But it doesn't change the fact that they should be supported.

[Shinigami92]

Hello @lydell

I am interested in designing a new, better configuration structure
I'm not saying that I have a good knowledge of it, but I want to help in this topic

I think about things like:

• What is the best way to be compatible with as many languages as possible?
• Is yaml maybe better and should json be the second preferred way?
• Should we support to extend the configuration file?
• Should we allow top level configurations like useTabs?
• Isn't it better to use indent: { type: 'space', width: 2 }? Is the eslint-way better? indent: ['space', 2]?
• ...

[lydell]

What is the best way to be compatible with as many languages as possible?

What do you mean?

Is yaml maybe better and should json be the second preferred way?

I’d say we should strive for making Prettier configs so simple that a more advanced language than JSON isn’t needed.

Should we support to extend the configuration file?

No. We discussed this when adding support for using config from an npm package, and I haven’t seen this requested. Keep it simple.

Should we allow top level configurations like useTabs?

Yes. That’s what I call “global” options in the OP.

Isn't it better to use indent: { type: 'space', width: 2 }? Is the eslint-way better? indent: ['space', 2]?

Combining useTabs and tabWidth sounds good to me.

...

Yes. There will be a lot of questions and decisions to make if doing this.

[Shinigami92]

What do you mean?

Structure

I’d say we should strive for making Prettier configs so simple that a more advanced language than JSON isn’t needed.

Is yaml easier than json? Is json easier than yaml? And why?

No. We discussed this when adding support for using config from an npm package, and I haven’t seen this requested. Keep it simple.

👍

Combining useTabs and tabWidth sounds good to me.

👍

Yes. There will be a lot of questions and decisions to make if doing this.

👍

[lydell]

What do you mean?

Structure

Sorry, I’m not sure what you mean :) Could you elaborate and provide an example?

Is yaml easier than json? Is json easier than yaml? And why?

There is very little JSON syntax to learn. I use yaml every now and then, and I’m always unsure about how to indent, what | means and when to quote things. I think it could also be valuable for other tools that want to do stuff with Prettier’s config it was JSON. That’s very easy to parse and update.

[Shinigami92]

Sorry, I’m not sure what you mean :) Could you elaborate and provide an example?

Ok, so we have your example

{
  "useTabs": true,
  "javascript": {
    "singleQuote": true,
    "parser": "babel-flow"
  },
  "fileExtensions": {
    ".foo": "javascript"
  },
  "ignore": [
    "*.html",
    "/legacy/",
    { "include": "./.gitignore" },
    "!*.config.js"
  ]
}

Modified/brainstorming:

{
  "indent": ["spaces", 2],
  "printWidth": 120,
  "javascript": { // Is this a good idea? What if I want to use the same settings for js and ts? What's with jsx and tsx?
    "parser": "babel-flow",
    "preferredQuotes": "single"
  },
  "fileExtensions": { // Is this solving a problem? Or does it only flatten `overrides` 🤔 
    ".foo": "javascript"
  },
  "ignore": [
    "*.html",
    "/legacy/",
    { "include": "./.gitignore" },
    "!*.config.js"
  ]
}

In vscode settings I'm seeing something like "[javascript]": {...}
Does this have any reason? We should find out :)

We should support json5!!! (comments)

We should use readable keys like preferredQuotes
I think it's more friendly and also indicates that it isn't force and something like "It's me" and 'Quotes in long texts are surrounded by "' is possible
We could also use "quotes": "single"?!

Should we have a "plugins": [...] field? So only these plugins are used?! (Defaults to current behaviour / all installed plugins) Can this shorten loadtimes? 🤷‍♂️

Could we allow custom defined objects/structures for plugins?
-> I have a draft of sorting for pug-attributes: https://github.com/prettier/plugin-pug/blob/feature/sort-attributes/src/options/index.ts#L110
But as you can see, I'm forces to use a string-array as value
But it could help me to also allow regex patterns or objects with plugin-self-defined structure

... Some more ideas I currently dont know :D

There is very little JSON syntax to learn. I use yaml every now and then, and I’m always unsure about how to indent, what | means and when to quote things. I think it could also be valuable for other tools that want to do stuff with Prettier’s config it was JSON. That’s very easy to parse and update.

👍

[lydell]

"javascript": { // Is this a good idea? What if I want to use the same settings for js and ts? What's with jsx and tsx?

Want the same settings for ts as js? Duplicate js.

jsx and tsx – are you thinking about jsxSingleQuote and jsxBracketSameLine? Maybe they should be separate languages as well. "jsx": {

"fileExtensions": { // Is this solving a problem?

We support setting parser: "babel" or whatever on unknown file types today via overrides. But maybe people don’t use this so much. I have never used it myself.

We should use readable keys like preferredQuotes

"preferredQuotes": "single" sounds good to me.

We should support json5!!! (comments)

If you need comments in your Prettier config you are doing your config wrong, IMO.

I really like editing JSON with VSCode by the way when there’s a schema for it. Then you don’t need to type the quotes (they are autocompleted) and you get help will all keys and get documentation inline.

Should we have a "plugins": [...] field? So only these plugins are used?! (Defaults to current behaviour / all installed plugins) Can this shorten loadtimes?

Could be worth exploring.

Could we allow custom defined objects/structures for plugins?

Sounds like a good idea to me.

[Shinigami92]

Want the same settings for ts as js? Duplicate js.

mhhh but isn't this ... duplicated 😅

jsx and tsx – are you thinking about jsxSingleQuote and jsxBracketSameLine? Maybe they should be separate languages as well. "jsx": {

Havn't thought about jsxSingleQuote, but yeah you are also right with this 👍

We support setting parser: "babel" or whatever on unknown file types today via overrides. But maybe people don’t use this so much. I have never used it myself.

I suggest this currently to support different quotes in pug along with js: https://github.com/prettier/plugin-pug#prettier-options

"preferredQuotes": "single" sounds good to me.

👍

We should support json5!!! (comments)

If you need comments in your Prettier config you are doing your config wrong, IMO.

What if someone want to add a TODO comment in the config? IMO: It wont hurt it to support it.

I really like editing JSON with VSCode by the way when there’s a schema for it. Then you don’t need to type the quotes (they are autocompleted) and you get help will all keys and get documentation inline.

👍 -> Schema is a must have today for a good tool
But how can we support plugin values?!

plugins field?

Could be worth exploring.

👍

Custom defined objects/structures for plugins?

Sounds like a good idea to me.

👍

[bakkot]

Prettier advocates for few options, but our configuration is super complicated!

Wait, what? How so? You maybe pass one or two option flags if you don't like the defaults, you specify if you want to overwrite files or print to stdout, and you name the files you want to format. Am I missing some complexity here?

A prettier.json should be required for Prettier to run – this makes Prettier opt-in.

I am pretty strongly opposed to this, fwiw. I very regularly run prettier on random JavaScript files - things I found on the internet, things in node_modules I'm trying to understand or debug, legacy code, whatever. (I have alias pw="prettier --single-quote --write" in my .zshrc on every machine I use regularly.) npx prettier` when on a coworker's machine. I think it would be a pretty bad to decide this was not a supported use case.

[lydell]

Wait, what? How so?

I’m referring to that we support a hundred different file names and languages and .editorconfig and whatnot. And that you have to use globs if you want different settings for some language.

I very regularly run prettier on random JavaScript files

I do, too, sometimes. That’s why I wrote this sketch in the OP:

A --force flag could be used for one-off formatting of files with no prettier.json. That would use the default options. --config ~/foo/prettier.json could use a specified one.

[bakkot]

I’m referring to that we support a hundred different file names and languages and .editorconfig and whatnot.

Sure, I suppose it can be complicated if you're running prettier against a whole project with multiple file types all at once, though most of the complexity is in specifying which files to run on and from interactions between languages.

For my part, I'm accustomed to using prettier in projects where I am just formatting everything in src/ and test/ (which are exclusively .js and/or .ts files) with exactly the same options - which is, I think, a pretty common case - and so this pretty much doesn't come up.

A --force flag could be used for one-off formatting of files with no prettier.json.

Sure but... why? What's the point of the flag? Why not just continue to work correctly without it?

And why limit it so much, so that people have to create a config file if they just want to tweak one setting for printing one file? That's the part I really don't get. The CLI works simply and well right now if you are not trying to fuss with multiple file types in the same directory structure; I don't understand where the desire to restrict it comes from. Yes, if people are having trouble with configuration for complicated projects we should look into improving our file-based config, but for the many people for whom prettier --single-quote --write src currently works fine, why take that away?

[fregante]

Edit: moved to #9271

[kachkaev]

WRT "plugins". Seems like this is an unavoidable part of the config for Yarn PnP / v2 (Berry) projects. Because there is no node_modules, plugin autodiscovery does not work. What we'll need in .prettierrc.js is:

module.exports = {
  trailingComma: true,
  whateverElse: true,
  plugins: [
     require.resolve("prettier-plugin-xyz"),
     require.resolve("@prettier/prettier-xyz"),
  ]
}

I'm happy to explore this further in a separate issue if there is a chance we can add plugins field to the config before the rest of the discussed changes (many of which are not backwards-compatible). If plugins field is present in the config file, autodiscovery would stop and Prettier would only use the plugins it was pointed to. Because of require.resolve, things should work even if a plugin is installed in a company-wide config. I.e.:

// .prettierrc.js
module.exports = require.resolve("@my-company/prettier-config");

// @my-company/prettier-config/package.json
{
  "dependencies": {
    "@prettier/prettier-xyz": "^4.2.0",
    "prettier-plugin-xyz": "^0.4.2"
  },
  "main": "index.js"
}

// @my-company/prettier-config/index.js
module.exports = {
  optionA: true,
  optionB: 42,
  plugins: [
      require.resolve("prettier-plugin-xyz"),
      require.resolve("@prettier/prettier-xyz"),
  ]
}

My experiments with Yarn Berry and Prettier so far have failed for Prettier plugins. Even if I add the plugins to project deps (i.e. not via @my-company/prettier-config), they are not discovered and therefore not applied.

[lydell]

@kachkaev Feel free to explore something outside of this proposal, too! I’m afraid this proposal is too ambitious. Since Prettier 2.0 shipped with such good prettier --write . support I lost a lot of motivation on this one.

[thorn0]

@kachkaev plugins in the config is already supported. It can contain both strings to resolve and plugin objects. A config can't be async though.

[fisker]

Really? I thought it's only supported in options and cli arguments?

[thorn0]

Yep, I checked.

[kachkaev]

Wow! config → plugins works indeed and this trick is also compatible with Yarn PnP / v2! Terrific! I just tweaked my personal shared Prettier config, updated the config package in kachkaev/njt#29 and Prettier picked the right plugins! I did not have to add them as the project dependencies, having @kachkaev/prettier-config was enough! 🕺

Perhaps, we could improve docs to help Yarn PnP / v2 Berry folks with their shared config? Lack of node_modules in such setups makes plugin autodiscovery unavailable, so setting config → plugins becomes only working solution.

[thorn0]

Autodiscovery based on package.json, discussed in #8474, should improve this situation. But while we don't have it, sure, a docs PR would be great.

[dustin-ruetz]

Wow! config → plugins works indeed and this trick is also compatible with Yarn PnP / v2! Terrific! I just tweaked my personal shared Prettier config, updated the config package in kachkaev/njt#29 and Prettier picked the right plugins! I did not have to add them as the project dependencies, having @kachkaev/prettier-config was enough! 🕺

Perhaps, we could improve docs to help Yarn PnP / v2 Berry folks with their shared config? Lack of node_modules in such setups makes plugin autodiscovery unavailable, so setting config → plugins becomes only working solution.

@kachkaev - I'm curious, do you also use Visual Studio Code and the "Prettier - Code formatter" extension as well?

I'm trying to get a similar thing working with the @prettier/plugin-pug package, where I can install said plugin as a devDependency in my NPM config library without also having to explicitly install it as a dependency in every other repository that consumes said NPM config library.

Currently when I use npm run format then Prettier will format the .pug files correctly, but on saving a .pug file in VS Code the Prettier extension does not auto-format it.

Obviously I'm happy that my format script works, but I do miss the "auto-format on file save" functionality that Prettier provides for other files. Below is a trimmed version of my Prettier config file.

// .prettierrc.js
module.exports = {
  // ... prettier-specific config trimmed ...
  plugins: [require('@prettier/plugin-pug')]
  // ... pug-specific config trimmed ...
}

(Also tagging @Shinigami92 because they are the author of the @prettier/plugin-pug package.)

[Shinigami92]

@dustin-ruetz thanks for tagging

Do other plugins work with autoformat? Like e.g. https://github.com/simonhaenisch/prettier-plugin-organize-imports

If not it's a problem of VSCode or an extension.
Otherwise tomorrow I may try some scenarios if I find some time for that 🙂

[kachkaev]

@dustin-ruetz, given that you’ve mentioned npm run format, I think that our setup is different. I was talking about Prettier plugins working with Yarn Berry (PnP), which did work in kachkaev/njt#29 without problems. Note that there's .vscode/settings.json file with "prettier.prettierPath": ".yarn/sdks/prettier/index.js" as well as the referenced file. That’s what lets Prettier VSCode extension pick the right Prettier instance, which can do plugin resolution correctly.

Most of my projects still have a good old node_modules folder and Yarn v1. Prettier VSCode extension works there even if .prettierrc.js mentions plugins as strings, i.e. without require. Unfortunately, I haven't used npm (with and without PnP) for a while, so I'm not sure how to help specifically on this tool.