From e7ca215c3c2f0c634b18a86c72b9c7fcae6614f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lehoczky=20Zolt=C3=A1n?= Date: Fri, 18 Oct 2024 08:57:01 +0200 Subject: [PATCH] docs: add detailed guide for shared configs (#16495) --- cspell.json | 3 + docs/configuration.md | 31 --- docs/sharing-configurations.md | 216 +++++++++++++++++ website/sidebars.json | 6 +- .../version-stable/configuration.md | 31 --- .../version-stable/sharing-configurations.md | 217 ++++++++++++++++++ .../version-stable-sidebars.json | 3 +- 7 files changed, 443 insertions(+), 64 deletions(-) create mode 100644 docs/sharing-configurations.md create mode 100644 website/versioned_docs/version-stable/sharing-configurations.md diff --git a/cspell.json b/cspell.json index 972595f8a..6004870cd 100644 --- a/cspell.json +++ b/cspell.json @@ -59,6 +59,7 @@ "decf", "defun", "Deloise", + "Denicola", "deopt", "devcontainer", "devs", @@ -66,6 +67,7 @@ "doctag", "Dodds", "Dolzhykov", + "Domenic", "Doshi", "duailibe", "Duperron", @@ -197,6 +199,7 @@ "normalise", "normalised", "Nowak", + "npmjs", "Nuno", "nvim", "octicon", diff --git a/docs/configuration.md b/docs/configuration.md index 5e701dfdf..7afd43007 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -135,37 +135,6 @@ overrides: `files` is required for each override, and may be a string or array of strings. `excludeFiles` may be optionally provided to exclude files for a given rule, and may also be a string or array of strings. -## Sharing configurations - -Sharing a Prettier configuration is simple: just publish a module that exports a configuration object, say `@company/prettier-config`, and reference it in your `package.json`: - -```json -{ - "name": "my-cool-library", - "version": "9000.0.1", - "prettier": "@company/prettier-config" -} -``` - -If you don’t want to use `package.json`, you can use any of the supported extensions to export a string, e.g. `.prettierrc.json`: - -```json -"@company/prettier-config" -``` - -An example configuration repository is available [here](https://github.com/azz/prettier-config). - -> Note: This method does **not** offer a way to _extend_ the configuration to overwrite some properties from the shared configuration. If you need to do that, import the file in a `.prettierrc.js` file and export the modifications, e.g: -> -> ```js -> import companyPrettierConfig from "@company/prettier-config"; -> -> export default { -> ...companyPrettierConfig, -> semi: false, -> }; -> ``` - ## Setting the [parser](options.md#parser) option By default, Prettier automatically infers which parser to use based on the input file extension. Combined with `overrides` you can teach Prettier how to parse files it does not recognize. diff --git a/docs/sharing-configurations.md b/docs/sharing-configurations.md new file mode 100644 index 000000000..d95674a98 --- /dev/null +++ b/docs/sharing-configurations.md @@ -0,0 +1,216 @@ +--- +id: sharing-configurations +title: Sharing configurations +--- + +In case you have many different projects, it can be helpful to have a **shared configuration** which can be used in all of them, instead of copy-pasting the same config for every project. + +This page explains how to create, publish and consume a shareable config. + +## Creating a Shareable Config + +Sharable configs are just [npm packages](https://docs.npmjs.com/about-packages-and-modules#about-packages) that export a single [prettier config file](./configuration.md). + +Before we start, make sure you have: + +- An account for [npmjs.com](https://www.npmjs.com/) to publish the package +- Basic understating about [how to create a Node.js module](https://docs.npmjs.com/creating-node-js-modules) + +First, create a new package. We recommend creating a [scoped package](https://docs.npmjs.com/cli/v10/using-npm/scope) with the name `@username/prettier-config`. + +A minimal package should have at least two files. A `package.json` for the package configuration and an `index.js` which holds the shared prettier configuration object: + +```text +prettier-config/ +├── index.js +└── package.json +``` + +Example `package.json`: + +```json +{ + "name": "@username/prettier-config", + "version": "1.0.0", + "description": "My personal Prettier config", + "type": "module", + "exports": "./index.js", + "license": "MIT", + "publishConfig": { + "access": "public" + }, + "peerDependencies": { + "prettier": ">=3.0.0" + } +} +``` + +`index.js` is where you put the shared configuration. This file just exports a [regular prettier configuration](./configuration.md) with the same syntax and same options: + +```js +const config = { + trailingComma: "es5", + tabWidth: 4, + singleQuote: true, +}; + +export default config; +``` + +An example shared configuration repository is available [here](https://github.com/azz/prettier-config). + +## Publishing a Shareable Config + +Once you are ready, you can [publish your package to npm](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages#publishing-scoped-public-packages): + +```bash +npm publish +``` + +## Using a Shareable Config + +You first need to install your published configuration, for example: + + + + +```bash +npm install --save-dev @username/prettier-config +``` + + + +```bash +yarn add --dev @username/prettier-config +``` + + + +```bash +pnpm add --save-dev @username/prettier-config +``` + + + +```bash +bun add --dev @username/prettier-config +``` + + + +Then, you can reference it in your `package.json`: + +```json +{ + "name": "my-cool-library", + "version": "1.0.0", + "prettier": "@username/prettier-config" +} +``` + +If you don’t want to use `package.json`, you can use any of the supported extensions to export a string, e.g. `.prettierrc`: + +```json +"@company/prettier-config" +``` + +### Extending a Sharable Config + +To _extend_ the configuration to overwrite some properties from the shared configuration, import the file in a `.prettierrc.mjs` file and export the modifications, e.g: + +```js +import usernamePrettierConfig from "@username/prettier-config"; + +/** + * @type {import("prettier").Config} + */ +const config = { + ...usernamePrettierConfig, + semi: false, +}; + +export default config; +``` + +## Other examples + +### Using Type Annotation in the Shared Config + +You can get type safety and autocomplete support in your shared configuration by using a `jsdoc` type annotation: + +```js +/** + * @type {import("prettier").Config} + */ +const config = { + trailingComma: "es5", + tabWidth: 4, + semi: false, + singleQuote: true, +}; + +export default config; +``` + +In order to make this work, you have to [install `prettier`](./install.md) for the project. + +After that, your `package.json` file should look like this: + +```diff +{ + "name": "@username/prettier-config", + "version": "1.0.0", + "description": "My personal Prettier config", + "type": "module", + "exports": "./index.js", + "license": "MIT", + "publishConfig": { + "access": "public" + }, + "peerDependencies": { + "prettier": ">=3.0.0" + }, ++ "devDependencies": { ++ "prettier": "^3.3.3" ++ } +} +``` + +### Include Plugins in Shareable Configurations + +In case you want to use [plugins](./plugins.md) in your shared configuration, you need to declare those plugins in the config file's `plugin` array and as `dependencies` in `package.json`: + +```js +// index.js +const config = { + singleQuote: true, + plugins: ["prettier-plugin-xml"], +}; + +export default config; +``` + +```diff +// package.json +{ + "name": "@username/prettier-config", + "version": "1.0.0", + "description": "My personal Prettier config", + "type": "module", + "exports": "./index.js", + "license": "MIT", + "publishConfig": { + "access": "public" + }, ++ "dependencies": { ++ "prettier-plugin-xml": "3.4.1" ++ }, + "peerDependencies": { + "prettier": ">=3.0.0" + } +} +``` + +An example repository can be found [here](https://github.com/kachkaev/routine-npm-packages/tree/bc3e658f88c0b41beb118c7a1b9b91ec647f8478/packages/prettier-config) + +**Note:** You can use [`peerDependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies) instead of [`dependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies). To learn about their differences, you can read [this blog post from Domenic Denicola about peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies) diff --git a/website/sidebars.json b/website/sidebars.json index 0ee505526..2dbaa9ced 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -17,7 +17,11 @@ "api", "browser" ], - "Configuring Prettier": ["options", "configuration"], + "Configuring Prettier": [ + "options", + "configuration", + "sharing-configurations" + ], "Editors": ["editors", "webstorm", "vim", "watching-files"], "Misc": ["technical-details", "related-projects", "for-enterprise"] } diff --git a/website/versioned_docs/version-stable/configuration.md b/website/versioned_docs/version-stable/configuration.md index 7a0a60636..204ed88a8 100644 --- a/website/versioned_docs/version-stable/configuration.md +++ b/website/versioned_docs/version-stable/configuration.md @@ -136,37 +136,6 @@ overrides: `files` is required for each override, and may be a string or array of strings. `excludeFiles` may be optionally provided to exclude files for a given rule, and may also be a string or array of strings. -## Sharing configurations - -Sharing a Prettier configuration is simple: just publish a module that exports a configuration object, say `@company/prettier-config`, and reference it in your `package.json`: - -```json -{ - "name": "my-cool-library", - "version": "9000.0.1", - "prettier": "@company/prettier-config" -} -``` - -If you don’t want to use `package.json`, you can use any of the supported extensions to export a string, e.g. `.prettierrc.json`: - -```json -"@company/prettier-config" -``` - -An example configuration repository is available [here](https://github.com/azz/prettier-config). - -> Note: This method does **not** offer a way to _extend_ the configuration to overwrite some properties from the shared configuration. If you need to do that, import the file in a `.prettierrc.js` file and export the modifications, e.g: -> -> ```js -> import companyPrettierConfig from "@company/prettier-config"; -> -> export default { -> ...companyPrettierConfig, -> semi: false, -> }; -> ``` - ## Setting the [parser](options.md#parser) option By default, Prettier automatically infers which parser to use based on the input file extension. Combined with `overrides` you can teach Prettier how to parse files it does not recognize. diff --git a/website/versioned_docs/version-stable/sharing-configurations.md b/website/versioned_docs/version-stable/sharing-configurations.md new file mode 100644 index 000000000..fdf15bbb1 --- /dev/null +++ b/website/versioned_docs/version-stable/sharing-configurations.md @@ -0,0 +1,217 @@ +--- +id: version-stable-sharing-configurations +title: Sharing configurations +original_id: sharing-configurations +--- + +In case you have many different projects, it can be helpful to have a **shared configuration** which can be used in all of them, instead of copy-pasting the same config for every project. + +This page explains how to create, publish and consume a shareable config. + +## Creating a Shareable Config + +Sharable configs are just [npm packages](https://docs.npmjs.com/about-packages-and-modules#about-packages) that export a single [prettier config file](./configuration.md). + +Before we start, make sure you have: + +- An account for [npmjs.com](https://www.npmjs.com/) to publish the package +- Basic understating about [how to create a Node.js module](https://docs.npmjs.com/creating-node-js-modules) + +First, create a new package. We recommend creating a [scoped package](https://docs.npmjs.com/cli/v10/using-npm/scope) with the name `@username/prettier-config`. + +A minimal package should have at least two files. A `package.json` for the package configuration and an `index.js` which holds the shared prettier configuration object: + +```text +prettier-config/ +├── index.js +└── package.json +``` + +Example `package.json`: + +```json +{ + "name": "@username/prettier-config", + "version": "1.0.0", + "description": "My personal Prettier config", + "type": "module", + "exports": "./index.js", + "license": "MIT", + "publishConfig": { + "access": "public" + }, + "peerDependencies": { + "prettier": ">=3.0.0" + } +} +``` + +`index.js` is where you put the shared configuration. This file just exports a [regular prettier configuration](./configuration.md) with the same syntax and same options: + +```js +const config = { + trailingComma: "es5", + tabWidth: 4, + singleQuote: true, +}; + +export default config; +``` + +An example shared configuration repository is available [here](https://github.com/azz/prettier-config). + +## Publishing a Shareable Config + +Once you are ready, you can [publish your package to npm](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages#publishing-scoped-public-packages): + +```bash +npm publish +``` + +## Using a Shareable Config + +You first need to install your published configuration, for example: + + + + +```bash +npm install --save-dev @username/prettier-config +``` + + + +```bash +yarn add --dev @username/prettier-config +``` + + + +```bash +pnpm add --save-dev @username/prettier-config +``` + + + +```bash +bun add --dev @username/prettier-config +``` + + + +Then, you can reference it in your `package.json`: + +```json +{ + "name": "my-cool-library", + "version": "1.0.0", + "prettier": "@username/prettier-config" +} +``` + +If you don’t want to use `package.json`, you can use any of the supported extensions to export a string, e.g. `.prettierrc`: + +```json +"@company/prettier-config" +``` + +### Extending a Sharable Config + +To _extend_ the configuration to overwrite some properties from the shared configuration, import the file in a `.prettierrc.mjs` file and export the modifications, e.g: + +```js +import usernamePrettierConfig from "@username/prettier-config"; + +/** + * @type {import("prettier").Config} + */ +const config = { + ...usernamePrettierConfig, + semi: false, +}; + +export default config; +``` + +## Other examples + +### Using Type Annotation in the Shared Config + +You can get type safety and autocomplete support in your shared configuration by using a `jsdoc` type annotation: + +```js +/** + * @type {import("prettier").Config} + */ +const config = { + trailingComma: "es5", + tabWidth: 4, + semi: false, + singleQuote: true, +}; + +export default config; +``` + +In order to make this work, you have to [install `prettier`](./install.md) for the project. + +After that, your `package.json` file should look like this: + +```diff +{ + "name": "@username/prettier-config", + "version": "1.0.0", + "description": "My personal Prettier config", + "type": "module", + "exports": "./index.js", + "license": "MIT", + "publishConfig": { + "access": "public" + }, + "peerDependencies": { + "prettier": ">=3.0.0" + }, ++ "devDependencies": { ++ "prettier": "^3.3.3" ++ } +} +``` + +### Include Plugins in Shareable Configurations + +In case you want to use [plugins](./plugins.md) in your shared configuration, you need to declare those plugins in the config file's `plugin` array and as `dependencies` in `package.json`: + +```js +// index.js +const config = { + singleQuote: true, + plugins: ["prettier-plugin-xml"], +}; + +export default config; +``` + +```diff +// package.json +{ + "name": "@username/prettier-config", + "version": "1.0.0", + "description": "My personal Prettier config", + "type": "module", + "exports": "./index.js", + "license": "MIT", + "publishConfig": { + "access": "public" + }, ++ "dependencies": { ++ "prettier-plugin-xml": "3.4.1" ++ }, + "peerDependencies": { + "prettier": ">=3.0.0" + } +} +``` + +An example repository can be found [here](https://github.com/kachkaev/routine-npm-packages/tree/bc3e658f88c0b41beb118c7a1b9b91ec647f8478/packages/prettier-config) + +**Note:** You can use [`peerDependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies) instead of [`dependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies). To learn about their differences, you can read [this blog post from Domenic Denicola about peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies) diff --git a/website/versioned_sidebars/version-stable-sidebars.json b/website/versioned_sidebars/version-stable-sidebars.json index 719e0d077..c799bdb2e 100644 --- a/website/versioned_sidebars/version-stable-sidebars.json +++ b/website/versioned_sidebars/version-stable-sidebars.json @@ -19,7 +19,8 @@ ], "Configuring Prettier": [ "version-stable-options", - "version-stable-configuration" + "version-stable-configuration", + "version-stable-sharing-configurations" ], "Editors": [ "version-stable-editors",