Lacking documentation of using postcss with `tailwindcss-rails

[leewaa]

Unfortunately it is not totally clear what is required in order to use PostCSS with this Gem.

The Readme simply states to add the config file but does not describe any other prerequisites or setup requirements.

There are very many ways in which one can add postcss with many Rails applications running different setups (webpacker/sprockets/importman/yarn/node/etc) but this is not clear enough in the readme. It would be nice if this section had more information and explicit setup instructions to use postcss with tailwindcss-rails.

Simply installing this gem, running ./bin/rails tailwindcss:install and then adding the postcss.config.js example file as described, does not work out of the box. Would be very helpful with extended information.

[flavorjones]

The postcss functionality and docs were added in #316 by @ahmeij, and those instructions work for me.

Can you paste the output from rails tailwindcss:build[verbose], please? I'd like to see if the --postcss option is being injected properly.

[leewaa]

$ rails tailwindcss:build[verbose]
warning: parser/current is loading parser/ruby32, which recognizes 3.2.5-compliant syntax, but you are running 3.2.3.
Please see https://github.com/whitequark/parser#compatibility-with-ruby-mri.
["bundle exec tailwindcss build", "--minify", "-i /Users/peter.lehwess/development/15habits/15-habits-web/app/assets/stylesheets/admin.tailwind.css", "-o /Users/peter.lehwess/development/15habits/15-habits-web/app/assets/builds/tailwind-admin.css", "-c /Users/peter.lehwess/development/15habits/15-habits-web/config/tailwind-admin.config.js"]
["/Users/peter.lehwess/.gem/ruby/3.2.3/gems/tailwindcss-rails-2.7.2-arm64-darwin/exe/arm64-darwin/tailwindcss", "build", "--minify", "-i", "/Users/peter.lehwess/development/15habits/15-habits-web/app/assets/stylesheets/admin.tailwind.css", "-o", "/Users/peter.lehwess/development/15habits/15-habits-web/app/assets/builds/tailwind-admin.css", "-c", "/Users/peter.lehwess/development/15habits/15-habits-web/config/tailwind-admin.config.js"]

Rebuilding...

Done in 315ms.
["/Users/peter.lehwess/.gem/ruby/3.2.3/gems/tailwindcss-rails-2.7.2-arm64-darwin/exe/arm64-darwin/tailwindcss", "-i", "/Users/peter.lehwess/development/15habits/15-habits-web/app/assets/stylesheets/application.tailwind.css", "-o", "/Users/peter.lehwess/development/15habits/15-habits-web/app/assets/builds/tailwind.css", "-c", "/Users/peter.lehwess/development/15habits/15-habits-web/config/tailwind.config.js", "--minify"]

Rebuilding...

Done in 364ms.

[flavorjones]

@leewaa I don't see the --postcss argument being injected into the tailwindcss command. Here's how that's supposed to work:

https://github.com/rails/tailwindcss-rails/blob/main/lib/tailwindcss/commands.rb#L86-L87

       postcss_path = Rails.root.join("config/postcss.config.js")
       command += ["--postcss", postcss_path.to_s] if File.exist?(postcss_path)

Can you take a look at your project files and make sure you've got the postcss file in the right place?

[flavorjones]

I'd also like to add: this is a community-supported project, and the maintainers don't happen to use postcss, so we're likely unaware of rough edges. We would definitely welcome improvements to the documentation!

[ahmeij]

As far as I know Tailwind uses Postcss under the hood in all cases (the project is also sponsored by tailwind). Tailwind describes how to setup Tailwind with Postcss here: https://tailwindcss.com/docs/installation/using-postcss

The layer that tailwindcss-rails adds is only very thin, it checks if the file exists and if so it will add it to the command line parameters of the tailwind executable.

Hopefully the above will help you get it working. Without more information I don't know what to add, a more detailed problem description would be helpful

[alvincrespo]

I'm running into the same issue:

/snapshot/tailwindcss/node_modules/postcss-load-config/src/plugins.js:28
    throw new Error(`Loading PostCSS Plugin failed: ${err.message}\n\n(@${file})`)
          ^

Error: Loading PostCSS Plugin failed: Cannot find module 'postcss-import'
Require stack:
- /Users/alvincrespo/workspace/jardim/app/config/postcss.config.js
1) If you want to compile the package/file into executable, please pay attention to compilation warnings and specify a literal in 'require' call. 2) If you don't want to compile the package/file into executable and want to 'require' it from filesystem (likely plugin), specify an absolute path in 'require' call using process.cwd() or process.execPath.

(@/Users/alvincrespo/workspace/jardim/app/config/postcss.config.js)
    at load (/snapshot/tailwindcss/node_modules/postcss-load-config/src/plugins.js:28:11)
    at /snapshot/tailwindcss/node_modules/postcss-load-config/src/plugins.js:53:16
    at Array.map (<anonymous>)
    at plugins (/snapshot/tailwindcss/node_modules/postcss-load-config/src/plugins.js:52:8)
    at /snapshot/tailwindcss/lib/cli/build/plugin.js:57:43
    at async loadPostCssPlugins (/snapshot/tailwindcss/lib/cli/build/plugin.js:42:38)
    at async createProcessor (/snapshot/tailwindcss/lib/cli/build/plugin.js:228:74)
    at async build (/snapshot/tailwindcss/lib/cli/build/index.js:39:21)

From what I understand, PostCSS needs to be installed via npm and pre-processes the CSS using JavaScript. However, I don't see any integration with npm and/or node and was confirmed here. It looks like we're passing the option but it doesn't actually do anything? Any thoughts here?

This does make sense though from Tailwind's docs:

Install tailwindcss and its peer dependencies via npm, and create your tailwind.config.js file.

If thats the case, I think we would need to go the standard NPM installation route if we're looking to extend tailwind "functionality".

[alvincrespo]

Ok. Following up, it's as simple as just running an npm install of postcss. This is my package.json:

{
  "name": "myapp",
  "private": true,
  "engines": {
    "node": "20.10.0",
    "yarn": "1.22.21",
    "npm": "10.2.5"
  },
  "dependencies": {
    "postcss": "^8.4.41",
    "postcss-flexbugs-fixes": "^5.0.2",
    "postcss-import": "^16.1.0",
    "postcss-loader": "^8.1.1",
    "postcss-preset-env": "^10.0.0"
  },
  "version": "0.1.0",
  "browserslist": [
    "defaults"
  ]
}

One you run npm install. Things should work as expected. There might be an opportunity to streamline things here but maybe adding this to the README would help? Thoughts @flavorjones @ahmeij ?

[flavorjones]

@alvincrespo We'd welcome documentation improvements about how to integrate with postcss. Are you up for creating a PR to extend (or replace) the current "Using with PostCSS" section in the README?

[alvincrespo]

@flavorjones Yeah definitely! Will do. Thank you for the direction there.