Skip to content

Commit fbad419

Browse files
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
1 parent 08c989c commit fbad419

2 files changed

Lines changed: 24 additions & 4 deletions

File tree

‎docs/guidelines/plugin.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,15 +108,17 @@ It is better even not to import `postcss`.
108108
Plugin name will be used in error messages and warnings.
109109

110110
```js
111-
module.exports = opts => {
111+
const plugin = opts => {
112112
return {
113113
postcssPlugin: 'postcss-name',
114114
Once(root) {
115115
// Plugin code
116116
}
117117
}
118118
}
119-
module.exports.postcss = true
119+
plugin.postcss = true
120+
121+
export default plugin
120122
```
121123

122124
## 2. Processing

‎docs/writing-a-plugin.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,14 +91,32 @@ For public plugins:
9191
3. Publish your code there.
9292

9393
```js
94-
module.exports = (opts = {}) => {
94+
const plugin = (opts = {}) => {
9595
// Plugin creator to check options or prepare shared state
9696
return {
9797
postcssPlugin: 'PLUGIN NAME'
9898
// Plugin listeners
9999
}
100100
}
101-
module.exports.postcss = true
101+
plugin.postcss = true
102+
103+
export default plugin
104+
```
105+
106+
In TypeScript, type the creator as `PluginCreator` so `postcss = true` is valid:
107+
108+
```ts
109+
import type { PluginCreator } from 'postcss'
110+
111+
const plugin: PluginCreator<object> = (opts = {}) => {
112+
return {
113+
postcssPlugin: 'PLUGIN NAME'
114+
// Plugin listeners
115+
}
116+
}
117+
plugin.postcss = true
118+
119+
export default plugin
102120
```
103121

104122
[PostCSS plugin boilerplate]: https://github.com/postcss/postcss-plugin-boilerplate/

0 commit comments

Comments
 (0)