testea/test-repo
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add detailed guide for shared configs (#16495)

Browse Source
This commit is contained in:
Lehoczky Zoltán authored and GitHub committed 2024-10-18 14:57:01 +08:00
1 parent 1e73934cae
commit e7ca215c3c
7 files changed
+443 -64
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

cspell.json
+3
View File
@@ -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",
docs/configuration.md
-31
View File
@@ -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.
docs/sharing-configurations.md
+216
View File
@@ -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:
<!--DOCUSAURUS_CODE_TABS-->
<!--npm-->
```bash
npm install --save-dev @username/prettier-config
```
<!--yarn-->
```bash
yarn add --dev @username/prettier-config
```
<!--pnpm-->
```bash
pnpm add --save-dev @username/prettier-config
```
<!--bun-->
```bash
bun add --dev @username/prettier-config
```
<!--END_DOCUSAURUS_CODE_TABS-->
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)
website/sidebars.json
+5 -1
View File
@@ -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"]
}
website/versioned_docs/version-stable/configuration.md
-31
View File
@@ -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.
website/versioned_docs/version-stable/sharing-configurations.md
+217
View File
@@ -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:
<!--DOCUSAURUS_CODE_TABS-->
<!--npm-->
```bash
npm install --save-dev @username/prettier-config
```
<!--yarn-->
```bash
yarn add --dev @username/prettier-config
```
<!--pnpm-->
```bash
pnpm add --save-dev @username/prettier-config
```
<!--bun-->
```bash
bun add --dev @username/prettier-config
```
<!--END_DOCUSAURUS_CODE_TABS-->
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)
website/versioned_sidebars/version-stable-sidebars.json
+2 -1
View File
@@ -19,7 +19,8 @@
],
"Configuring Prettier": [
"version-stable-options",
"version-stable-configuration"
"version-stable-configuration",
"version-stable-sharing-configurations"
],
"Editors": [
"version-stable-editors",