From 91735fedf39aa79d34d6f41278bdb77d10c9dd15 Mon Sep 17 00:00:00 2001
From: Joe Haddad <joe.haddad@zeit.co>
Date: Thu, 23 Jan 2020 16:11:11 -0500
Subject: [PATCH 1/2] Error on Invalid PostCSS Shape

---
 errors/postcss-shape.md                       | 127 ++++++++++++++++++
 .../webpack/config/blocks/css/plugins.ts      |  11 +-
 2 files changed, 134 insertions(+), 4 deletions(-)
 create mode 100644 errors/postcss-shape.md

diff --git a/errors/postcss-shape.md b/errors/postcss-shape.md
new file mode 100644
index 000000000000000..272a6e26e599cd2
--- /dev/null
+++ b/errors/postcss-shape.md
@@ -0,0 +1,127 @@
+# Invalid PostCSS Configuration
+
+#### Why This Error Occurred
+
+PostCSS configuration was provided in an unsupported shape.
+
+#### Possible Ways to Fix It
+
+PostCSS configuration must be defined in the following shape:
+
+```js
+module.exports = {
+  plugins: [
+    // A plugin that does not require configuration:
+    'simple-plugin-example',
+
+    // A plugin which needs a configuration object:
+    [
+      'plugin-with-configuration',
+      {
+        optionA: '...',
+      },
+    ],
+
+    // A plugin that is toggled on or off based on environment:
+    [
+      'plugin-toggled',
+      process.env.NODE_ENV === 'production'
+        ? {
+            optionA: '...',
+          }
+        : false,
+    ],
+
+    // Boolean expressions are also valid.
+    // `true` enables the plugin, `false` disables the plugin:
+    ['plugin-toggled-2', true /* a === b, etc */],
+  ],
+}
+```
+
+#### Common Errors
+
+**Before: plugin is require()'d**
+
+```js
+const pluginA = require('postcss-plugin-a')
+module.exports = {
+  plugins: [require('postcss-plugin'), pluginA],
+}
+```
+
+**After**
+
+```js
+module.exports = {
+  plugins: ['postcss-plugin', 'postcss-plugin-a'],
+}
+```
+
+---
+
+**Before: plugin is instantiated with configuration**
+
+```js
+module.exports = {
+  plugins: [
+    require('postcss-plugin')({
+      optionA: '...',
+    }),
+  ],
+}
+```
+
+**After**
+
+```js
+module.exports = {
+  plugins: [
+    // Pay attention to this nested array. The first index is the plugin name,
+    // the second index is the configuration.
+    [
+      'postcss-plugin',
+      {
+        optionA: '...',
+      },
+    ],
+  ],
+}
+```
+
+---
+
+**Before: plugin is missing configuration**
+
+```js
+module.exports = {
+  plugins: [
+    [
+      'postcss-plugin-1',
+      {
+        optionA: '...',
+      },
+    ],
+    // This single-entry array is detected as misconfigured because it's
+    // missing the second element. To fix, unwrap the value.
+    ['postcss-plugin-2'],
+  ],
+}
+```
+
+**After**
+
+```js
+module.exports = {
+  plugins: [
+    [
+      'postcss-plugin-1',
+      {
+        optionA: '...',
+      },
+    ],
+    // Only string:
+    'postcss-plugin-2',
+  ],
+}
+```
diff --git a/packages/next/build/webpack/config/blocks/css/plugins.ts b/packages/next/build/webpack/config/blocks/css/plugins.ts
index 30a8e39be03997d..0720d341f7b4b2b 100644
--- a/packages/next/build/webpack/config/blocks/css/plugins.ts
+++ b/packages/next/build/webpack/config/blocks/css/plugins.ts
@@ -184,13 +184,15 @@ export async function getPostCssPlugins(
               'Error'
             )}: A PostCSS Plugin must be provided as a ${chalk.bold(
               'string'
-            )}. Instead, we got: '${pluginName}'.`
+            )}. Instead, we got: '${pluginName}'.\n` +
+              'Read more: https://err.sh/next.js/postcss-shape'
           )
         } else {
           console.error(
             `${chalk.red.bold(
               'Error'
-            )}: A PostCSS Plugin was passed as an array but did not provide its configuration ('${pluginName}').`
+            )}: A PostCSS Plugin was passed as an array but did not provide its configuration ('${pluginName}').\n` +
+              'Read more: https://err.sh/next.js/postcss-shape'
           )
         }
         throw new Error(genericErrorText)
@@ -201,14 +203,15 @@ export async function getPostCssPlugins(
           'Error'
         )}: A PostCSS Plugin was passed as a function using require(), but it must be provided as a ${chalk.bold(
           'string'
-        )}.`
+        )}.\nRead more: https://err.sh/next.js/postcss-shape`
       )
       throw new Error(genericErrorText)
     } else {
       console.error(
         `${chalk.red.bold(
           'Error'
-        )}: An unknown PostCSS plugin was provided (${plugin}).`
+        )}: An unknown PostCSS plugin was provided (${plugin}).\n` +
+          'Read more: https://err.sh/next.js/postcss-shape'
       )
       throw new Error(genericErrorText)
     }

From 1d3a3137dd02bcb92b5fd232921e3cd23a1f787a Mon Sep 17 00:00:00 2001
From: Joe Haddad <joe.haddad@zeit.co>
Date: Thu, 23 Jan 2020 16:18:21 -0500
Subject: [PATCH 2/2] Add link to docs

---
 errors/postcss-shape.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/errors/postcss-shape.md b/errors/postcss-shape.md
index 272a6e26e599cd2..889fe55bcbc680a 100644
--- a/errors/postcss-shape.md
+++ b/errors/postcss-shape.md
@@ -39,6 +39,8 @@ module.exports = {
 }
 ```
 
+You can [read more](https://nextjs.org/docs/advanced-features/customizing-postcss-config) about configuring PostCSS in Next.js [here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
+
 #### Common Errors
 
 **Before: plugin is require()'d**