docs: add detailed guide for shared configs #16495
Conversation
docs/sharing-configurations.md
Outdated
| "name": "@username/prettier-config", | ||
| "version": "1.0.0", | ||
| "description": "My personal Prettier config", | ||
| "main": "index.mjs", // <-- change index.json to index.mjs |
There was a problem hiding this comment.
Even though main works as well, I'm happy to change it to a modern alternative! What do you think about updating it everywhere in the examples, even for the json configuration?
Otherwise only changing it for the JavaScript example might confuse people.
There was a problem hiding this comment.
Although this might still be confusing, because the provided example form Alexander uses main too:
docs/sharing-configurations.md
Outdated
|
|
||
| ## Other examples | ||
|
|
||
| ### Sharing a JavaScript Configuration File |
There was a problem hiding this comment.
Do you mean to rewrite the first part of the guide to ESM instead of a json export? Sounds good to me!
I will create an example repository then, because https://github.com/azz/prettier-config is using a json file. And the new example will also use the exports field.
There was a problem hiding this comment.
I will create an example repository then, because azz/prettier-config is using a json file. And the new example will also use the exports field.
@azz Will you accept PR change your example to ESM?
There was a problem hiding this comment.
Done 👍 Now the example uses an ESM file, and I've also added the exports and type fields to the example package.json.
| const config = { | ||
| singleQuote: true, | ||
| plugins: ["prettier-plugin-xml"], | ||
| }; |
There was a problem hiding this comment.
The recommended way to use plugin should be
import * as prettierPluginXml ...
const config = {
singleQuote: true,
plugins: [prettierPluginXml],
};But vscode-prettier cannot work since they transfer config to worker.
My suggestion is to use an absolute path/url instead, but import.meta.resolve is under --experimental-import-meta-resolve flag. Not sure what's the best way here.
There was a problem hiding this comment.
Fortunately import.meta.resolve by itself is not under a flag, only if someone wants to its second parameter:
My issue is now that I've got an error from the vscode-prettier extension that it cannot find the module @prettier/plugin-xml/src/plugin.js. I'm gonna open a separate issue there.
What do you think about merging this PR without this section about sharing configurations with plugins? It could be added later in a follow up PR easily.
There was a problem hiding this comment.
I'm gonna open a separate issue there.
The issue is here in Prettier.
There was a problem hiding this comment.
Fortunately import.meta.resolve by itself is not under a flag,
We still support Node.js v14.
There was a problem hiding this comment.
What do you think about merging this PR without this section about sharing configurations with plugins? It could be added later in a follow up PR easily.
The example should work for everyone, give me a while to think about it.
There was a problem hiding this comment.
Sure thing! Take as much time as needed, I'm gonna update the PR when necessary^^
There was a problem hiding this comment.
Sorry for leaving this for such a long time. Let's merge with current example.
|
Can you fix the spellcheck? |
✅ lint command is passing now^^ |
Description
This PR moves the the sharing-configurations paragraph from the Configuration File page to its own subpage and guides readers through the creation of a shared config in more details.
Motivation
After looking for a way to add plugins to a shared config, I found #15667 and I wanted to add this information to the docs, because plugins are getting used more and more with for example prettier-plugin-tailwindcss and prettier-plugin-svelte.
Why a new page?
I believe adding this information to the existing "Configuration File" page would just clutter up that page, so I extracted it to a new one. This is also how the ESLint's documentation is organized: there is a Configuration Files and a Share Configurations page.
Detailed explanation for creating a shared config
The existing docs very briefly says how to create a shared config, it is mostly about how to use them:
This can be confusing for people who never created an
npmpackage before, and can also make them feel dumb by not knowing how to "just publish a module that exports a configuration object".Now that the shared configuration section had its own page, I wanted to make it more friendly for newcomers and write a more detailed guide for sharing a configuration. The structure was also inspired by ESLint, where there are these sections for the Share Configurations:
Notes
I wanted the docs to be detailed, but not going into too deep about how npm packages work. This is why there are multiple links to the npm docs. I hope I found a good balance between detailed steps for the reader, and linking to other docs when it is needed.
Of course I'm not a native speaker, so there might be mistakes in the text.
Checklist
docs/directory).changelog_unreleased/*/XXXX.mdfile followingchangelog_unreleased/TEMPLATE.md.✨Try the playground for this PR✨