What exactly are the rules for configuring postcss.config.js (mainly with tailwndcss)?

Question

UPDATE (2024-05-29): Since there are still people who provide answers (thank you!) I would like to point out that I provided the proper solution/approach with my own answer already. My error was the spelling in example 2, which actually needs brackets instead of curly braces!

---

[Original Post]

The number of variants that exist to showcase how postcss.config.js has to be configured is extremely confusing. There are examples (like the one at the tailwindcss documentation) that use this:

// Example 1:
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

then there are those which require the libraries:

// Example 2:
module.exports = {
  plugins: {
    require('tailwindcss'),
    require('postcss-preset-env')({
      stage: 0,
      'nesting-rules': true
    })
  },
}

Others require external libs before they configure module.exports:

// Example 3:

const tailwindcss = require('tailwindcss');
const postcssPresetEnv = require('postcss-preset-env');


module.exports = {
  plugins: {
    tailwindcss,
    postcssPresetEnv
  },
}

and again some more that are necessary, when a configuration file that is not named according to the defaults has to be incorporated.

Today I get this error, when running yarn dev with a postcss.config.js as show in Example 2:

Syntax Error: /[path]/_pod-test/postcss.config.js:3
    require('tailwindcss'),
             ^^^^^^^^^^^

SyntaxError: Unexpected string

When I remove the line with "tailwindcss", the same thing happens for "postcss-preset-env":

Syntax Error: /Volumes/_III_/Z_WWW/_ZZZ PoD/_pod-test/postcss.config.js:3
    require('postcss-preset-env')({
            ^^^^^^^^^^^^^^^^^^^^

SyntaxError: Unexpected string

When I then switch to a setup as shown in example 1, I get this error:

Syntax Error: Error: PostCSS plugin tailwindcss requires PostCSS 8.
Migration guide for end-users:
https://github.com/postcss/postcss/wiki/PostCSS-8-for-end-users

I do use postcss 8.3.9!

This all happens in a project that was setup with vue-cli as a Vue2 project.

Which witch craft do I have to apply to make this setup work?

Briney

Answer 1

There is a subtle, but very important difference between examples 1 and 2 that I posted.

Example 2 is actually wrong!

While example 1 uses objects to configure the parameters of the plugins, the 2nd example uses function calls. And those must be put in an ARRAY (meaning: brackets instead of curly braces).

This would be correct version of Example 2:

// Example 2 fixed:

module.exports = {
  plugins: [  // <= here we MUST use brackets!
    ... [function calls] ...
  ],
}

I have not yet tested if that is also true for example 3 (but I assume so).

Hope this helps somebody!

Briney

Can some one atleast point to official postcss docs where it explains how to configure postcssconfig and explains both syntax – Gebelein

Answer 2

In package.json I have:

  "postcss": {
    "plugins": [
      "postcss-import",
      "tailwindcss",
      "postcss-preset-env",
      "autoprefixer",
      "cssnano"
    ]
  }

That's my full setup for production. I have tailwind 3.0.23, but it probably works with any version anyway.

If you use cssnano, you don't need to set the tailwindcss/nesting for postcss-preset-env which tailwind recommends in their docs: https://tailwindcss.com/docs/using-with-preprocessors#nesting

Why? because cssnano merges the repeated code that they both produces. This workaround with cssnano is recommended by one of the tailwind team member: https://github.com/tailwindlabs/tailwindcss/issues/4634#issuecomment-861392246

Giannini

Thank you, Lucas! Meanwhile - since we have a new tailwind version - it would be of great help, if you could mention whether your config is valid for tailwind v2 and / or v3 (only). – Briney

I have version 3.0.23 of tailwind, but I think it's compatible with any version because this config is more related to postcss than tailwind. – Giannini

Answer 3

In your terminal run the below command to install tailwind css and its dependencies via npm.

npm install tailwindcss postcss autoprefixer

It is possible to get the error message that you mentioned when you try to run the project

Error: PostCSS plugin tailwindcss requires PostCSS 8.

Run the following code to uninstall previous installation and fix the error

npm uninstall tailwindcss postcss autoprefixer 
npm install tailwindcss@npm:@tailwindcss/postcss7-compat@tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

Next, you need to generate both Tailwind and PostCSS config files

npx tailwindcss init -p

Your config files should look like this

postcss.config file

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

tailwindcss.config file

module.exports = {
  future: {
    // removeDeprecatedGapUtilities: true,
    // purgeLayersByDefault: true,
  },
  purge: [],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
};

Finally, open up your main.js file and import the tailwind.css file containing the tailwind directives i.e

import './css/tailwind.css'

Cribriform

Thank you, I know about the downgrade path (should have mentioned it). The culprit is the postcss-preset-env. There is no one standard that seems to work, neither with react, nor vue (also not with vue & vite). postcss is pretty broken ATM. – Briney

Answer 4

for me is THIS config that can run correctly :

// Example 3:

const tailwindcss = require('tailwindcss');
const postcssPresetEnv = require('postcss-preset-env');


module.exports = {
  plugins: {
    tailwindcss,
    postcssPresetEnv
  },
}

and with this versions libraries :

"postcss": "^8.4.6",
"postcss-cli": "^9.1.0",
"tailwindcss": "^3.0.18",

I do not try all features postcss at this time but basic process file into CLI run correctly...

Inexpedient