gatsby-plugin-postcss configuration option postCssPlugins does not work as documented

[richardxia]

Description

According to https://github.com/gatsbyjs/gatsby/blob/3a3c3e7f0942578b5ee113056d4883c7c277bdd3/docs/docs/post-css.md and https://github.com/gatsbyjs/gatsby/blob/3a3c3e7f0942578b5ee113056d4883c7c277bdd3/packages/gatsby-plugin-postcss/README.md, one should be able to configure custom PostCSS plugins with Gatsby by adding the following to gatsby-config.js:

plugins: [
  {
    resolve: `gatsby-plugin-postcss`,
    options: {
      postCssPlugins: [require(`postcss-preset-env`)({ stage: 0 })],
    },
  },
],

However, when I actually try running Gatsby with those settings, I get the following error message:

Generating development JavaScript bundle failed

Invalid options object. PostCSS Loader has been initialized using an options object that does not match the API schema.
 - options has an unknown property 'plugins'. These properties are valid:
   object { postcssOptions?, execute?, sourceMap? }

Steps to reproduce

# Create new Gatsby site
$ gatsby new gatsby-site https://github.com/gatsbyjs/gatsby-starter-hello-world
$ cd gatsby-site

# Install and configure PostCSS as described in Gatsby docs
$ npm install postcss gatsby-plugin-postcss postcss-preset-env
# Open gatsby-config.js and add plugin exactly as described above
$ cat > gatsby-config.js <<-'EOF'
module.exports = {
  /* Your site config here */
  plugins: [
    {
      resolve: `gatsby-plugin-postcss`,
      options: {
        postCssPlugins: [require(`postcss-preset-env`)({ stage: 0 })],
      },
    },
  ],
}
EOF

# Create .css file and add to main page
$ touch src/pages/main.css
$ echo 'import "./main.css"' | cat - src/pages/index.js > tmp && mv tmp src/pages/index.js

# Start Gatsby development server
$ gatsby develop

Expected result

The site builds.

Actual result

The following error message is printed:

Generating development JavaScript bundle failed

Invalid options object. PostCSS Loader has been initialized using an options object that does not match the API schema.
 - options has an unknown property 'plugins'. These properties are valid:
   object { postcssOptions?, execute?, sourceMap? }

Environment

I'm going to redact some of this information because I don't think it's relevant and it could be used for device fingerprinting.

  System:
    OS: macOS Mojave 10.14.6
    Shell: 3.2.57 - /bin/bash
  Binaries:
    Node: 14.13.0 - ~/.nvm/versions/node/v14.13.0/bin/node
    npm: 6.14.8 - ~/.nvm/versions/node/v14.13.0/bin/npm
  Languages:
    Python: 2.7.16 - /usr/bin/python
  Browsers:
  npmPackages:
    gatsby: ^2.24.67 => 2.24.67
    gatsby-plugin-postcss: ^3.0.1 => 3.0.1

[jbFeDev]

@LekoArts this issue still occurs to me using gatsby-plugin-css@3.0.2. I don't know why... I've followed the official documentation...

[richardxia]

Yeah, sorry about that, I also noticed that my PR didn't fully fix the problem. I wrote some more information in #27418 (comment) on what I learned, and I have a followup PR to try to fix it for real: #27430.

[richardxia]

@jbFeDev, this should be fixed now, so please try again with the new gatsby-plugin-css@3.0.3.