From 9bb9556bb3963b16a322c7e7084ac6982dc86281 Mon Sep 17 00:00:00 2001 From: Seiya <20365512+seiyab@users.noreply.github.com> Date: Sat, 20 Sep 2025 20:31:14 +0900 Subject: [PATCH] Encourage namespace import from `prettier` (#17928) Co-authored-by: fisker Cheung --- docs/plugins.md | 19 +++++++++-------- .../versioned_docs/version-stable/plugins.md | 21 ++++++++++--------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index ffa5732d4..6e635e77f 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -184,9 +184,9 @@ export const printers = { Prettier uses an intermediate representation, called a Doc, which Prettier then turns into a string (based on options like `printWidth`). A _printer_'s job is to take the AST generated by `parsers[].parse` and return a Doc. A Doc is constructed using [builder commands](https://github.com/prettier/prettier/blob/main/commands.md): ```js -import { doc } from "prettier"; +import * as prettier from "prettier"; -const { join, line, ifBreak, group } = doc.builders; +const { join, line, ifBreak, group } = prettier.doc.builders; ``` The printing process consists of the following steps: @@ -221,9 +221,9 @@ The `print` function is passed the following parameters: Here’s a simplified example to give an idea of what a typical implementation of `print` looks like: ```js -import { doc } from "prettier"; +import * as prettier from "prettier"; -const { group, indent, join, line, softline } = doc.builders; +const { group, indent, join, line, softline } = prettier.doc.builders; function print(path, options, print) { const node = path.node; @@ -460,15 +460,15 @@ At the time of dispatching, Prettier will have annotated each AST comment node ( #### Manually attaching a comment -The `util.addTrailingComment`/`addLeadingComment`/`addDanglingComment` functions can be used to manually attach a comment to an AST node. An example `ownLine` function that ensures a comment does not follow a "punctuation" node (made up for demonstration purposes) might look like: +The `prettier.util.addTrailingComment`/`addLeadingComment`/`addDanglingComment` functions can be used to manually attach a comment to an AST node. An example `ownLine` function that ensures a comment does not follow a "punctuation" node (made up for demonstration purposes) might look like: ```js -import { util } from "prettier"; +import * as prettier from "prettier"; function ownLine(comment, text, options, ast, isLastComment) { const { precedingNode } = comment; if (precedingNode && precedingNode.type === "punctuation") { - util.addTrailingComment(precedingNode, comment); + prettier.util.addTrailingComment(precedingNode, comment); return true; } return false; @@ -479,7 +479,7 @@ Nodes with comments are expected to have a `comments` property containing an arr -The example above uses `util.addTrailingComment`, which automatically sets `comment.leading`/`trailing`/`printed` to appropriate values and adds the comment to the AST node's `comments` array. +The example above uses `prettier.util.addTrailingComment`, which automatically sets `comment.leading`/`trailing`/`printed` to appropriate values and adds the comment to the AST node's `comments` array. The `--debug-print-comments` CLI flag can help with debugging comment attachment issues. It prints a detailed list of comments, which includes information on how every comment was classified (`ownLine`/`endOfLine`/`remaining`, `leading`/`trailing`/`dangling`) and to which node it was attached. For Prettier’s built-in languages, this information is also available on the Playground (the 'show comments' checkbox in the Debug section). @@ -638,10 +638,11 @@ Since plugins can be resolved using relative paths, when working on one you can ```js import * as prettier from "prettier"; + const code = "(add 1 2)"; await prettier.format(code, { parser: "lisp", - plugins: ["."], + plugins: ["./index.js"], }); ``` diff --git a/website/versioned_docs/version-stable/plugins.md b/website/versioned_docs/version-stable/plugins.md index e7e6c8864..240c22eae 100644 --- a/website/versioned_docs/version-stable/plugins.md +++ b/website/versioned_docs/version-stable/plugins.md @@ -183,9 +183,9 @@ export const printers = { Prettier uses an intermediate representation, called a Doc, which Prettier then turns into a string (based on options like `printWidth`). A _printer_'s job is to take the AST generated by `parsers[].parse` and return a Doc. A Doc is constructed using [builder commands](https://github.com/prettier/prettier/blob/main/commands.md): ```js -import { doc } from "prettier"; +import * as prettier from "prettier"; -const { join, line, ifBreak, group } = doc.builders; +const { join, line, ifBreak, group } = prettier.doc.builders; ``` The printing process consists of the following steps: @@ -220,9 +220,9 @@ The `print` function is passed the following parameters: Here’s a simplified example to give an idea of what a typical implementation of `print` looks like: ```js -import { doc } from "prettier"; +import * as prettier from "prettier"; -const { group, indent, join, line, softline } = doc.builders; +const { group, indent, join, line, softline } = prettier.doc.builders; function print(path, options, print) { const node = path.node; @@ -459,15 +459,15 @@ At the time of dispatching, Prettier will have annotated each AST comment node ( #### Manually attaching a comment -The `util.addTrailingComment`/`addLeadingComment`/`addDanglingComment` functions can be used to manually attach a comment to an AST node. An example `ownLine` function that ensures a comment does not follow a "punctuation" node (made up for demonstration purposes) might look like: +The `prettier.util.addTrailingComment`/`addLeadingComment`/`addDanglingComment` functions can be used to manually attach a comment to an AST node. An example `ownLine` function that ensures a comment does not follow a "punctuation" node (made up for demonstration purposes) might look like: ```js -import { util } from "prettier"; +import * as prettier from "prettier"; function ownLine(comment, text, options, ast, isLastComment) { const { precedingNode } = comment; if (precedingNode && precedingNode.type === "punctuation") { - util.addTrailingComment(precedingNode, comment); + prettier.util.addTrailingComment(precedingNode, comment); return true; } return false; @@ -478,7 +478,7 @@ Nodes with comments are expected to have a `comments` property containing an arr -The example above uses `util.addTrailingComment`, which automatically sets `comment.leading`/`trailing`/`printed` to appropriate values and adds the comment to the AST node's `comments` array. +The example above uses `prettier.util.addTrailingComment`, which automatically sets `comment.leading`/`trailing`/`printed` to appropriate values and adds the comment to the AST node's `comments` array. The `--debug-print-comments` CLI flag can help with debugging comment attachment issues. It prints a detailed list of comments, which includes information on how every comment was classified (`ownLine`/`endOfLine`/`remaining`, `leading`/`trailing`/`dangling`) and to which node it was attached. For Prettier’s built-in languages, this information is also available on the Playground (the 'show comments' checkbox in the Debug section). @@ -517,7 +517,7 @@ export default { ### Utility functions -A `util` module from Prettier core is considered a private API and is not meant to be consumed by plugins. Instead, the `util-shared` module provides the following limited set of utility functions for plugins: +`prettier.util` provides the following limited set of utility functions for plugins: ```ts type Quote = '"' | "'"; @@ -637,10 +637,11 @@ Since plugins can be resolved using relative paths, when working on one you can ```js import * as prettier from "prettier"; + const code = "(add 1 2)"; await prettier.format(code, { parser: "lisp", - plugins: ["."], + plugins: ["./index.js"], }); ```