docs: show ESM and TypeScript plugin declaration (#2118)

* docs: show ESM and TypeScript plugin declaration

Document the maintainer-recommended pattern of setting postcss = true on
the creator function and default-exporting it, so ES modules and TypeScript
do not need module.exports.

Fixes #1771

* docs: make ESM the default plugin example
This commit is contained in:
Hashim Khan
2026-07-29 16:04:29 +02:00
committed by GitHub
parent ac033c8e47
commit 14f8d11a0c
2 changed files with 24 additions and 4 deletions
+4 -2
View File
@@ -108,7 +108,7 @@ It is better even not to import `postcss`.
Plugin name will be used in error messages and warnings.
```js
module.exports = opts => {
const plugin = opts => {
return {
postcssPlugin: 'postcss-name',
Once(root) {
@@ -116,7 +116,9 @@ module.exports = opts => {
}
}
}
module.exports.postcss = true
plugin.postcss = true
export default plugin
```
## 2. Processing
+20 -2
View File
@@ -91,14 +91,32 @@ For public plugins:
3. Publish your code there.
```js
module.exports = (opts = {}) => {
const plugin = (opts = {}) => {
// Plugin creator to check options or prepare shared state
return {
postcssPlugin: 'PLUGIN NAME'
// Plugin listeners
}
}
module.exports.postcss = true
plugin.postcss = true
export default plugin
```
In TypeScript, type the creator as `PluginCreator` so `postcss = true` is valid:
```ts
import type { PluginCreator } from 'postcss'
const plugin: PluginCreator<object> = (opts = {}) => {
return {
postcssPlugin: 'PLUGIN NAME'
// Plugin listeners
}
}
plugin.postcss = true
export default plugin
```
[PostCSS plugin boilerplate]: https://github.com/postcss/postcss-plugin-boilerplate/