Add ESM plugins support

docs/guidelines/plugin.md

@@ -72,14 +72,15 @@ It is better even not to import `postcss`.
 
 ```diff
 - const { list, decl } = require('postcss')
-  module.exports = opts => {
+  const plugin = opts => {
     postcssPlugin: 'postcss-name',
 -   Once (root) {
 +   Once (root, { list, decl }) {
       // Plugin code
     }
   }
-  module.exports.postcss = true
+  plugin.postcss = true
+  module.exports = plugin
 ```
 
 
@@ -88,15 +89,15 @@ 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) {
       // Plugin code
     }
   }
 }
-module.exports.postcss = true
+plugin.postcss = true
 ```
 
 
@@ -117,7 +118,7 @@ For example, use `fs.writeFile` instead of `fs.writeFileSync`:
 ```js
 let { readFile } = require('fs').promises
 
-module.exports = opts => {
+const plugin = opts => {
   return {
     postcssPlugin: 'plugin-inline',
     async Decl (decl) {
@@ -129,15 +130,15 @@ module.exports = opts => {
     }
   }
 }
-module.exports.postcss = true
+plugin.postcss = true
 ```
 
 ### 2.3. Use fast node’s scanning
 
 Subscribing for specific node type is much faster, than calling `walk*` method:
 
 ```diff
-  module.exports = {
+  const plugin = () => ({
     postcssPlugin: 'postcss-example',
 -   Once (root) {
 -     root.walkDecls(decl => {
@@ -147,15 +148,15 @@ Subscribing for specific node type is much faster, than calling `walk*` method:
 +   Declaration (decl) {
 +     // Faster
 +   }
-  }
-  module.exports.postcss = true
+  })
+  plugin.postcss = true
 ```
 
 But you can make scanning even faster, if you know, what declaration’s property
 or at-rule’s name do you need:
 
 ```diff
-  module.exports = {
+  const plugin = () => ({
     postcssPlugin: 'postcss-example',
 -   Declaration (decl) {
 -     if (decl.prop === 'color') {
@@ -167,8 +168,8 @@ or at-rule’s name do you need:
 +       // The fastest
 +     }
 +   }
-  }
-  module.exports.postcss = true
+  })
+  plugin.postcss = true
 ```
 
 

docs/writing-a-plugin.md

@@ -80,23 +80,26 @@ For public plugins:
 2. Create a repository on GitHub or GitLab.
 3. Publish your code there.
 
-You can also use [our Sharec config] to keep the best practices up to date.
-Every time when you will update the config, it will update development configs
-and development tools.
-
 ```js
-module.exports = (opts = {}) => {
+const plugin = (opts = {}) => {
   // Plugin creator to check options or prepare caches
   return {
     postcssPlugin: 'PLUGIN NAME'
     // Plugin listeners
   }
 }
-module.exports.postcss = true
+plugin.postcss = true
+
+module.exports = plugin
+```
+
+For ESM project replace last line with:
+
+```js
+export default plugin
 ```
 
 [PostCSS plugin boilerplate]: https://github.com/postcss/postcss-plugin-boilerplate/
-[our Sharec config]: https://github.com/postcss/postcss-sharec-config
 [plugin template]: https://github.com/postcss/postcss-plugin-boilerplate/blob/main/template/index.t.js
 
 
@@ -128,7 +131,7 @@ how PostCSS convert different CSS to AST.
 You can find all nodes with specific types by adding method to plugin object:
 
 ```js
-module.exports = (opts = {}) => {
+const plugin = (opts = {}) => {
   return {
     postcssPlugin: 'PLUGIN NAME',
     Once (root) {
@@ -139,7 +142,7 @@ module.exports = (opts = {}) => {
     }
   }
 }
-module.exports.postcss = true
+plugin.postcss = true
 ```
 
 Here is the full list of [plugin’s events](https://postcss.org/api/#plugin).
@@ -199,7 +202,7 @@ You may want to re-use some data between listeners. You can do with
 runtime-defined listeners:
 
 ```js
-module.exports = (opts = {}) => {
+const plugin = (opts = {}) => {
   return {
     postcssPlugin: 'vars-collector',
     prepare (result) {
@@ -217,6 +220,7 @@ module.exports = (opts = {}) => {
     }
   }
 }
+plugin.postcss = true
 ```
 
 You can use `prepare()` to generate listeners dynamically. For instance,

lib/processor.js

@@ -32,6 +32,9 @@ class Processor {
   normalize(plugins) {
     let normalized = []
     for (let i of plugins) {
+      if (i.__esModule && i.default) {
+        i = i.default
+      }
       if (i.postcss === true) {
         i = i()
       } else if (i.postcss) {

test/processor.test.ts

@@ -578,6 +578,14 @@ test('supports plugin creators returning processors', () => {
   equal(processor.plugins, [a])
 })
 
+test('supports default ESM export wrap for plugins', () => {
+  let a = (): void => {}
+  let mod = { __esModule: true, default: a } as any
+  let processor = new Processor()
+  processor.use(mod)
+  equal(processor.plugins, [a])
+})
+
 test('uses custom syntax for document', async () => {
   let customParser: Parser<Document> = () => {
     return new Document({