Release 2.8.0

.github/ISSUE_TEMPLATE/formatting.md

@@ -26,7 +26,7 @@ Don't fill the form below manually! Let a program create a report for you:
 
 -->
 
-**Prettier 2.7.1**
+**Prettier 2.8.0**
 [Playground link](https://prettier.io/playground/#.....)
 
 ```sh

.github/ISSUE_TEMPLATE/integration.md

@@ -20,7 +20,7 @@ BEFORE SUBMITTING AN ISSUE:
 
 **Environments:**
 
-- Prettier Version: 2.7.1
+- Prettier Version: 2.8.0
 - Running Prettier via: <!-- CLI, Node.js API, Browser API, etc. -->
 - Runtime: <!-- Node.js v14, Chrome v83, etc. -->
 - Operating System: <!-- Windows, Linux, macOS, etc. -->

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 2.8.0
+
+[diff](https://github.com/prettier/prettier/compare/2.7.1...2.8.0)
+
+🔗 [Release Notes](https://prettier.io/blog/2022/11/23/2.8.0.html)
+
 # 2.7.1
 
 [diff](https://github.com/prettier/prettier/compare/2.7.0...2.7.1)

docs/browser.md

@@ -20,8 +20,8 @@ Required options:
 
 - **`plugins`**: Unlike the `format` function from the [Node.js-based API](api.md#prettierformatsource--options), this function doesn’t load plugins automatically. The `plugins` option is required because all the parsers included in the Prettier package come as plugins (for reasons of file size). These plugins are files named
 
-  - `parser-*.js` in <https://unpkg.com/browse/prettier@2.7.1/> and
-  - `parser-*.mjs` in <https://unpkg.com/browse/prettier@2.7.1/esm/>
+  - `parser-*.js` in <https://unpkg.com/browse/prettier@2.8.0/> and
+  - `parser-*.mjs` in <https://unpkg.com/browse/prettier@2.8.0/esm/>
 
   You need to load the ones that you’re going to use and pass them to `prettier.format` using the `plugins` option.
 
@@ -32,8 +32,8 @@ See below for examples.
 ### Global
 
 ```html
-<script src="https://unpkg.com/prettier@2.7.1/standalone.js"></script>
-<script src="https://unpkg.com/prettier@2.7.1/parser-graphql.js"></script>
+<script src="https://unpkg.com/prettier@2.8.0/standalone.js"></script>
+<script src="https://unpkg.com/prettier@2.8.0/parser-graphql.js"></script>
 <script>
   prettier.format("type Query { hello: String }", {
     parser: "graphql",
@@ -48,8 +48,8 @@ Note that the [`unpkg` field](https://unpkg.com/#examples) in Prettier’s `pack
 
 ```html
 <script type="module">
-  import prettier from "https://unpkg.com/prettier@2.7.1/esm/standalone.mjs";
-  import parserGraphql from "https://unpkg.com/prettier@2.7.1/esm/parser-graphql.mjs";
+  import prettier from "https://unpkg.com/prettier@2.8.0/esm/standalone.mjs";
+  import parserGraphql from "https://unpkg.com/prettier@2.8.0/esm/parser-graphql.mjs";
 
   prettier.format("type Query { hello: String }", {
     parser: "graphql",
@@ -62,8 +62,8 @@ Note that the [`unpkg` field](https://unpkg.com/#examples) in Prettier’s `pack
 
 ```js
 define([
-  "https://unpkg.com/prettier@2.7.1/standalone.js",
-  "https://unpkg.com/prettier@2.7.1/parser-graphql.js",
+  "https://unpkg.com/prettier@2.8.0/standalone.js",
+  "https://unpkg.com/prettier@2.8.0/parser-graphql.js",
 ], (prettier, ...plugins) => {
   prettier.format("type Query { hello: String }", {
     parser: "graphql",
@@ -88,8 +88,8 @@ This syntax doesn’t necessarily work in the browser, but it can be used when b
 ### Worker
 
 ```js
-importScripts("https://unpkg.com/prettier@2.7.1/standalone.js");
-importScripts("https://unpkg.com/prettier@2.7.1/parser-graphql.js");
+importScripts("https://unpkg.com/prettier@2.8.0/standalone.js");
+importScripts("https://unpkg.com/prettier@2.8.0/parser-graphql.js");
 prettier.format("type Query { hello: String }", {
   parser: "graphql",
   plugins: prettierPlugins,
@@ -102,8 +102,8 @@ If you want to format [embedded code](options.md#embedded-language-formatting),
 
 ```html
 <script type="module">
-  import prettier from "https://unpkg.com/prettier@2.7.1/esm/standalone.mjs";
-  import parserBabel from "https://unpkg.com/prettier@2.7.1/esm/parser-babel.mjs";
+  import prettier from "https://unpkg.com/prettier@2.8.0/esm/standalone.mjs";
+  import parserBabel from "https://unpkg.com/prettier@2.8.0/esm/parser-babel.mjs";
 
   console.log(
     prettier.format("const html=/* HTML */ `<DIV> </DIV>`", {
@@ -119,9 +119,9 @@ The HTML code embedded in JavaScript stays unformatted because the `html` parser
 
 ```html
 <script type="module">
-  import prettier from "https://unpkg.com/prettier@2.7.1/esm/standalone.mjs";
-  import parserBabel from "https://unpkg.com/prettier@2.7.1/esm/parser-babel.mjs";
-  import parserHtml from "https://unpkg.com/prettier@2.7.1/esm/parser-html.mjs";
+  import prettier from "https://unpkg.com/prettier@2.8.0/esm/standalone.mjs";
+  import parserBabel from "https://unpkg.com/prettier@2.8.0/esm/parser-babel.mjs";
+  import parserHtml from "https://unpkg.com/prettier@2.8.0/esm/parser-html.mjs";
 
   console.log(
     prettier.format("const html=/* HTML */ `<DIV> </DIV>`", {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "prettier",
-  "version": "2.8.0-dev",
+  "version": "2.8.0",
   "description": "Prettier is an opinionated code formatter",
   "bin": "./bin/prettier.js",
   "repository": "prettier/prettier",

website/versioned_docs/version-stable/browser.md

@@ -21,8 +21,8 @@ Required options:
 
 - **`plugins`**: Unlike the `format` function from the [Node.js-based API](api.md#prettierformatsource--options), this function doesn’t load plugins automatically. The `plugins` option is required because all the parsers included in the Prettier package come as plugins (for reasons of file size). These plugins are files named
 
-  - `parser-*.js` in <https://unpkg.com/browse/prettier@2.7.1/> and
-  - `parser-*.mjs` in <https://unpkg.com/browse/prettier@2.7.1/esm/>
+  - `parser-*.js` in <https://unpkg.com/browse/prettier@2.8.0/> and
+  - `parser-*.mjs` in <https://unpkg.com/browse/prettier@2.8.0/esm/>
 
   You need to load the ones that you’re going to use and pass them to `prettier.format` using the `plugins` option.
 
@@ -33,8 +33,8 @@ See below for examples.
 ### Global
 
 ```html
-<script src="https://unpkg.com/prettier@2.7.1/standalone.js"></script>
-<script src="https://unpkg.com/prettier@2.7.1/parser-graphql.js"></script>
+<script src="https://unpkg.com/prettier@2.8.0/standalone.js"></script>
+<script src="https://unpkg.com/prettier@2.8.0/parser-graphql.js"></script>
 <script>
   prettier.format("type Query { hello: String }", {
     parser: "graphql",
@@ -49,8 +49,8 @@ Note that the [`unpkg` field](https://unpkg.com/#examples) in Prettier’s `pack
 
 ```html
 <script type="module">
-  import prettier from "https://unpkg.com/prettier@2.7.1/esm/standalone.mjs";
-  import parserGraphql from "https://unpkg.com/prettier@2.7.1/esm/parser-graphql.mjs";
+  import prettier from "https://unpkg.com/prettier@2.8.0/esm/standalone.mjs";
+  import parserGraphql from "https://unpkg.com/prettier@2.8.0/esm/parser-graphql.mjs";
 
   prettier.format("type Query { hello: String }", {
     parser: "graphql",
@@ -63,8 +63,8 @@ Note that the [`unpkg` field](https://unpkg.com/#examples) in Prettier’s `pack
 
 ```js
 define([
-  "https://unpkg.com/prettier@2.7.1/standalone.js",
-  "https://unpkg.com/prettier@2.7.1/parser-graphql.js",
+  "https://unpkg.com/prettier@2.8.0/standalone.js",
+  "https://unpkg.com/prettier@2.8.0/parser-graphql.js",
 ], (prettier, ...plugins) => {
   prettier.format("type Query { hello: String }", {
     parser: "graphql",
@@ -89,8 +89,8 @@ This syntax doesn’t necessarily work in the browser, but it can be used when b
 ### Worker
 
 ```js
-importScripts("https://unpkg.com/prettier@2.7.1/standalone.js");
-importScripts("https://unpkg.com/prettier@2.7.1/parser-graphql.js");
+importScripts("https://unpkg.com/prettier@2.8.0/standalone.js");
+importScripts("https://unpkg.com/prettier@2.8.0/parser-graphql.js");
 prettier.format("type Query { hello: String }", {
   parser: "graphql",
   plugins: prettierPlugins,
@@ -103,8 +103,8 @@ If you want to format [embedded code](options.md#embedded-language-formatting),
 
 ```html
 <script type="module">
-  import prettier from "https://unpkg.com/prettier@2.7.1/esm/standalone.mjs";
-  import parserBabel from "https://unpkg.com/prettier@2.7.1/esm/parser-babel.mjs";
+  import prettier from "https://unpkg.com/prettier@2.8.0/esm/standalone.mjs";
+  import parserBabel from "https://unpkg.com/prettier@2.8.0/esm/parser-babel.mjs";
 
   console.log(
     prettier.format("const html=/* HTML */ `<DIV> </DIV>`", {
@@ -120,9 +120,9 @@ The HTML code embedded in JavaScript stays unformatted because the `html` parser
 
 ```html
 <script type="module">
-  import prettier from "https://unpkg.com/prettier@2.7.1/esm/standalone.mjs";
-  import parserBabel from "https://unpkg.com/prettier@2.7.1/esm/parser-babel.mjs";
-  import parserHtml from "https://unpkg.com/prettier@2.7.1/esm/parser-html.mjs";
+  import prettier from "https://unpkg.com/prettier@2.8.0/esm/standalone.mjs";
+  import parserBabel from "https://unpkg.com/prettier@2.8.0/esm/parser-babel.mjs";
+  import parserHtml from "https://unpkg.com/prettier@2.8.0/esm/parser-html.mjs";
 
   console.log(
     prettier.format("const html=/* HTML */ `<DIV> </DIV>`", {

website/versioned_docs/version-stable/cli.md

@@ -226,6 +226,16 @@ Also, since the cache file is stored in `./node_modules/.cache/prettier/.prettie
 
 > Plugins version and implementation are not used as cache keys. We recommend that you delete the cache when updating plugins.
 
+## `--cache-location`
+
+Path to the cache file location used by `--cache` flag. If you don't explicit `--cache-location`, Prettier saves cache file at `./node_modules/.cache/prettier/.prettier-cache`.
+
+If a file path is passed, that file is used as the cache file.
+
+```bash
+prettier --write --cache --cache-location=my_cache_file src
+```
+
 ## `--cache-strategy`
 
 Strategy for the cache to use for detecting changed files. Can be either `metadata` or `content`.

website/versioned_docs/version-stable/install.md

@@ -104,7 +104,7 @@ For example, you can do the following to have Prettier run before each commit:
    ```bash
    npm install --save-dev husky lint-staged
    npx husky install
-   npm set-script prepare "husky install"
+   npm pkg set scripts.prepare="husky install"
    npx husky add .husky/pre-commit "npx lint-staged"
    ```
 
@@ -113,16 +113,14 @@ For example, you can do the following to have Prettier run before each commit:
    ```bash
    yarn add --dev husky lint-staged
    npx husky install
-   npm set-script prepare "husky install"
+   npm pkg set scripts.prepare="husky install"
    npx husky add .husky/pre-commit "npx lint-staged"
    ```
 
    > If you use Yarn 2, see https://typicode.github.io/husky/#/?id=yarn-2
 
    <!--END_DOCUSAURUS_CODE_TABS-->
 
-> Note: npm **set-script** command requires at least **npm v7.x**. See https://docs.npmjs.com/cli/v7/commands/npm-set-script.
-
 2. Add the following to your `package.json`:
 
 ```json

website/versioned_docs/version-stable/integrating-with-linters.md

@@ -30,7 +30,7 @@ The downsides of those plugins are:
 - They are slower than running Prettier directly.
 - They’re yet one layer of indirection where things may break.
 
-Finally, we have tools that run `prettier` and then immediately for example `eslint --fix` on files.
+Finally, we have tools that run `prettier` and then immediately lint files by running, for example, `eslint --fix` on them.
 
 - [prettier-eslint](https://github.com/prettier/prettier-eslint)
 - [prettier-stylelint](https://github.com/hugomrdias/prettier-stylelint)

website/versioned_docs/version-stable/plugins.md

@@ -59,16 +59,20 @@ To turn off plugin autoloading, use `--no-plugin-search` when using Prettier CLI
 ## Community Plugins
 
 - [`prettier-plugin-apex`](https://github.com/dangmai/prettier-plugin-apex) by [**@dangmai**](https://github.com/dangmai)
+- [`prettier-plugin-astro`](https://github.com/withastro/prettier-plugin-astro) by [**@withastro contributors**](https://github.com/withastro/prettier-plugin-astro/graphs/contributors)
 - [`prettier-plugin-elm`](https://github.com/gicentre/prettier-plugin-elm) by [**@giCentre**](https://github.com/gicentre)
 - [`prettier-plugin-erb`](https://github.com/adamzapasnik/prettier-plugin-erb) by [**@adamzapasnik**](https://github.com/adamzapasnik)
 - [`prettier-plugin-glsl`](https://github.com/NaridaL/glsl-language-toolkit/tree/main/packages/prettier-plugin-glsl) by [**@NaridaL**](https://github.com/NaridaL)
 - [`prettier-plugin-go-template`](https://github.com/NiklasPor/prettier-plugin-go-template) by [**@NiklasPor**](https://github.com/NiklasPor)
 - [`prettier-plugin-java`](https://github.com/jhipster/prettier-java) by [**@JHipster**](https://github.com/jhipster)
 - [`prettier-plugin-jsonata`](https://github.com/Stedi/prettier-plugin-jsonata) by [**@Stedi**](https://github.com/Stedi)
 - [`prettier-plugin-kotlin`](https://github.com/Angry-Potato/prettier-plugin-kotlin) by [**@Angry-Potato**](https://github.com/Angry-Potato)
+- [`prettier-plugin-motoko`](https://github.com/dfinity/prettier-plugin-motoko) by [**@dfinity**](https://github.com/dfinity)
+- [`prettier-plugin-nginx`](https://github.com/joedeandev/prettier-plugin-nginx) by [**@joedeandev**](https://github.com/joedeandev)
+- [`prettier-plugin-prisma`](https://github.com/umidbekk/prettier-plugin-prisma) by [**@umidbekk**](https://github.com/umidbekk)
 - [`prettier-plugin-properties`](https://github.com/eemeli/prettier-plugin-properties) by [**@eemeli**](https://github.com/eemeli)
-- [`prettier-plugin-rust`](https://github.com/jinxdash/prettier-plugin-rust) by [**@jinxdash**](https://github.com/jinxdash)
-- [`prettier-plugin-sh`](https://github.com/rx-ts/prettier/tree/master/packages/sh) by [**@JounQin**](https://github.com/JounQin)
+- [`prettier-plugin-sh`](https://github.com/un-ts/prettier/tree/master/packages/sh) by [**@JounQin**](https://github.com/JounQin)
+- [`prettier-plugin-sql`](https://github.com/un-ts/prettier/tree/master/packages/sql) by [**@JounQin**](https://github.com/JounQin)
 - [`prettier-plugin-solidity`](https://github.com/prettier-solidity/prettier-plugin-solidity) by [**@mattiaerre**](https://github.com/mattiaerre)
 - [`prettier-plugin-svelte`](https://github.com/UnwrittenFun/prettier-plugin-svelte) by [**@UnwrittenFun**](https://github.com/UnwrittenFun)
 - [`prettier-plugin-toml`](https://github.com/bd82/toml-tools/tree/master/packages/prettier-plugin-toml) by [**@bd82**](https://github.com/bd82)
@@ -161,6 +165,7 @@ export const printers = {
     canAttachComment,
     isBlockComment,
     printComment,
+    getCommentChildNodes,
     handleComments: {
       ownLine,
       endOfLine,
@@ -295,6 +300,21 @@ Comments are often not part of a language's AST and present a challenge for pret
 
 By default, if the AST has a top-level `comments` property, Prettier assumes that `comments` stores an array of comment nodes. Prettier will then use the provided `parsers[<plugin>].locStart`/`locEnd` functions to search for the AST node that each comment "belongs" to. Comments are then attached to these nodes **mutating the AST in the process**, and the `comments` property is deleted from the AST root. The `*Comment` functions are used to adjust Prettier's algorithm. Once the comments are attached to the AST, Prettier will automatically call the `printComment(path, options): Doc` function and insert the returned doc into the (hopefully) correct place.
 
+#### (optional) `getCommentChildNodes`
+
+By default, Prettier searches all object properties (except for a few predefined ones) of each node recursively. This function can be provided to override that behavior. It has the signature:
+
+```ts
+function getCommentChildNodes(
+  // The node whose children should be returned.
+  node: AST,
+  // Current options
+  options: object
+): AST[] | undefined;
+```
+
+Return `[]` if the node has no children or `undefined` to fall back on the default behavior.
+
 #### (optional) `printComment`
 
 Called whenever a comment node needs to be printed. It has the signature:

website/versioned_docs/version-stable/technical-details.md

@@ -10,4 +10,6 @@ The basic idea is that the printer takes an AST and returns an intermediate repr
 
 This means that most of the logic of printing an AST involves generating an abstract representation of the output involving certain commands. For example, `["(", line, arg, line, ")"]` would represent a concatenation of opening parens, an argument, and closing parens. But if that doesn’t fit on one line, the printer can break where `line` is specified.
 
+The [Playground](https://prettier.io/playground) has a special mode for exploring how Prettier’s intermediate representation is printed. To get there, open the sidebar (the "Show options" button) and set the `parser` option to the special value `doc-explorer`.
+
 More (rough) details can be found in [commands.md](https://github.com/prettier/prettier/blob/main/commands.md).