next.js: Non-standardized PostCSS config file doesn't support require statements

Bug report

Describe the bug

With the introduction of the marvelous Built-in CSS Support, a new non-standard PostCSS Config plugin syntax was introduced.

This syntax requires that plugins listed in postcss.config.js be strings rather than require statements. This breaks backwards compatibility and differs from the standard set by existing PostCSS documentation.

Additionally, this makes it tough (or impossible) to share a common PostCSS configuration with additional tools like Storybook.js.

To Reproduce

Steps to reproduce the behavior, please provide code snippets or a repository:

  1. yarn add -D tailwindcss autoprefixer
  2. Add the following postcss.config.js:
module.exports = {
  plugins: [
    require("tailwindcss"),
    require("autoprefixer")
  ]
};
  1. yarn next build

Expected behavior

  • The build succeeds, and either plugins imported with require() are supported
  • Or the build fails, and a more descriptive error is shown in the build log.

Screenshots

The following is shown when running next build:

Error: An unknown PostCSS plugin was provided (function creator() {
--
02:32:09 PM | var transformer = initializer.apply(void 0, arguments);
02:32:09 PM | transformer.postcssPlugin = name;
02:32:09 PM | transformer.postcssVersion = new _processor.default().version;
02:32:09 PM | return transformer;
02:32:09 PM | }).
02:32:09 PM | > Build error occurred

System information

  • OS: macOS
  • Version of Next.js: 9.2

Additional context

This work was likely done to be able to identify, dedupe, and acknowledge Next’s default PostCSS plugins — and it’s likely the solution to this issue is nothing more than better documentation.

Here are a couple proposed solutions:

1. Support require() statements in PostCSS config

I’d rely on @Timer’s knowledge here, as there are likely other consequences (notably: not being able to inspect and dedupe plugins).

2. Display a warning/error that indicates deprecated behavior

This would be a simple check in packages/next/build/webpack/config/blocks/css/plugins.ts to see if the plugin is a function:

else if (typeof plugin === 'function') {
  console.error(
    `${chalk.red.bold(
      'Error'
    )}: A PostCSS Plugin must be provided as a ${chalk.bold(
      'string'
    )}. Instead, we got a function imported with require().`
  )
}

I’m happy to submit PRs for either of these solutions! But looking for guidance from the core team.

About this issue

  • Original URL
  • State: closed
  • Created 7 years ago
  • Reactions: 9
  • Comments: 22 (13 by maintainers)

Commits related to this issue

Most upvoted comments

the workaround, for searchers finding this issue: my postcss.config.js previously looked like

module.exports = {
  plugins: [
    require('postcss-import'),
    require('tailwindcss'),
    require('postcss-preset-env')({ stage: 2 }),
  ],
};

but now looks like

module.exports = {
  plugins: {
    'postcss-import': {},
    tailwindcss: {},
    'postcss-preset-env': { stage: 2 },
  },
};

following the format from https://github.com/postcss/postcss-loader

The big motivator behind this restriction is because self-requireing code makes it impossible for us to cache CSS transformations.

In other words, we’d have to re-transform the CSS every time the application was edited—this is slow/suboptimal.

We have not yet documented PostCSS customization, but it’s coming soon!


re: sharing config

We do support a subset of postcss.config.js, as you posted above:

module.exports = {
  plugins: {
    'postcss-import': {},
    tailwindcss: {},
    'postcss-preset-env': { stage: 2 },
  },
};

@simonsmith you should be able to use the resolved file path as the plugin name:

// postcss.config.js or .postcssrc.js
module.exports = {
  plugins: [
    require.resolve('../my-plugin.js')
  ]
};

// or

module.exports = {
  plugins: [
    [require.resolve('../my-plugin.js'), { ... }]
  ]
};

Now explained in Next.js canaries with read more links.

it seems like you can use either format—adding purgecss to my config works just fine like so, following the config options from https://github.com/zeit/next.js/blob/canary/examples/with-tailwindcss/postcss.config.js

module.exports = {
  plugins: {
    'postcss-import': {},
    tailwindcss: {},
    ...(process.env.NODE_ENV === 'production'
      ? {
          '@fullhuman/postcss-purgecss': {
            content: ['./pages/**/*.{js,jsx,ts,tsx}', './components/**/*.{js,jsx,ts,tsx}'],
            defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || [],
          },
        }
      : {}),
    'postcss-preset-env': { stage: 2 },
  },
};

noting, in the case of tailwind, to ignore the base import

/* purgecss start ignore */
@import 'tailwindcss/base';
/* purgecss end ignore */

@import 'tailwindcss/components';

@import './my_styles.css';

@import 'tailwindcss/utilities';

I love the update! Running into a snag though. I can’t seem to use purgecss in my postcss.config.js file. It was working with next-css. No errors or warning.

const plugins = {
  'postcss-import': {},
  'tailwindcss': {},
  'postcss-preset-env': { stage: 0 },
}

// This branch definitly runs...
if (process.env.NODE_ENV === 'production') {
  // This doesn't seem to work. None of the css is purged...
  plugins['@fullhuman/postcss-purgecss'] = {
    content: [
      'pages/**/*.js',
      'containers/**/*.js',
      'components/**/*.js',
      'views/**/*.js',
    ],
    defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || [],
  }

  // Doubt I need this but leaving it here just in case...
  plugins['cssnano'] = {
    preset: ['default', {
      discardComments: {
        removeAll: true,
      },
    }],
  }
}

module.exports = {
  plugins,
}

Here’s an example for purgecss: https://github.com/zeit/next.js/blob/canary/examples/with-tailwindcss/postcss.config.js

cssnano is not needed (applied already by next).

Thanks @Timer — that’s really illuminating! And @shrugs’s syntax suggestion worked great for me 👍

That’s already added, try upgrading to next@canary to see it.

Try next@canary, the message was updated there

The action items we want to take are:

  1. Fully document how to customize PostCSS, both in an interoperable format and our “proprietary format” (identical to Babel)
  2. Add a special case for typeof ... === 'function' that explains to not require the plugin.

Feel free to send PRs!