diff --git a/errors/postcss-shape.md b/errors/postcss-shape.md new file mode 100644 index 000000000000..889fe55bcbc6 --- /dev/null +++ b/errors/postcss-shape.md @@ -0,0 +1,129 @@ +# 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 */], + ], +} +``` + +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** + +```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 30a8e39be039..0720d341f7b4 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) }