@astrojs/tailwind docs don't cover important use-cases with postcss etc

[firxworx]

📚 Subject area/topic

@astrojs/tailwind

📋 Suggested page

https://docs.astro.build/en/guides/integrations-guide/tailwind/

📋 General description or bullet points (if proposing new content)

The @astrojs/tailwind integration can be a bit confusing at first because it automagically does certain things behind the curtain that are not well documented (I had to read the plugin code).

In fact, I recall one of the earliest sources of confusion when I started with Astro was when I first added Tailwind because it was not clear what exactly the integration did or how it behaved, or why it deviated from the tailwind setup for every other framework. The experience takes something many devs are familiar with and confident with and turns it into something new that they are uncertain about.

Here's what I kindly propose that the guide cover to improve the docs and hence the Astro experience for the community :)

---

• Document the undocumented automagical behaviour in more clear way about what is actually happening:

  • will create a default postcss configuration as documented by taiwindcss with autoprefixer and optionally the nesting plugin (current wording isn't clear that its creating a postcss configuration and adding these plugins)

• Document how the integration works + behaves

  • does it overwrite or merge configurations and how?
    • how does it reconcile if a postcss.config.* exists?
    • what if an inline config (vite.config.postcss object in the Astro config) is specified?
    • what if both file exist and an inline configuration -- how does it behave!?
  • it'd be nice if there were a documented "blessed" or recommended approach documented (e.g. either inline or a separate file) and what happens with the built-in behaviour (e.g. "if I add a postcss plugin inline will the integration still add autoprefixer!?")

Definitely check vs. the code :) https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/src/index.ts

• Add specific scenario documentation for the use-case of adding a postcss plugin because this is a very common thing to do (e.g. for polyfills, palettes, etc) especially on advanced projects + larger projects.

🖥️ Reproduction of code samples in StackBlitz

No response

[firxworx]

I did more homework into my use-case: requirement to add a custom plugin. I now honestly think it would actually be a better dev experience to nix the integration and simply provide instructions on the recommended way to directly integrate tailwind with Astro.

My $0.02 for recommended way would be to inline it in the astro->vite config which would also be best (imho) for different monorepo setups (its clear which postcss config to use vs. unpredictably-at-times scanning the project tree).

I realize this may be more controversial, disagreement and counterarguments welcome, here's my case:

---

I believe the following example replicates everything the integration does.

(caveat: with applyBaseStyles: false, which it seems a huge percentage of experienced astro+tailwind devs do anyway when looking at themes in the theme directory).

• I was able to put my plugin after tailwind and before autoprefixer, which it appears the integration cannot support
• ignoring the nesting (vite.css.postcss) I replaced the integration with what is really a one-liner in my astro config that I think is now more clear and explicit about tailwind/postcss behaviour vs. the integration config object that it replaces

  vite: {
    css: {
      postcss: {
        plugins: [tailwindcssNesting(), tailwindcss(), postCssOklabPolyfill({ preserve: true }), autoprefixer()],
      },
    },
  },

A tip that I learned from a comment in the integration code is that vite w/ postcss won't look for a config file if there's an inline config. I would def put that note in the docs!

Recalling back to my first experience with Astro and my first confusion point being the tailwind integration (I had previous experience setting up tailwind with other stacks), I would have not been confused with the above. It would have been one less "new concept" to learn.

I checked GitHub for astro configs that add postcss plugins and it appears to me that there is widespread misunderstanding about what the integration does and how it applies plugins, e.g. lots of cases where astro devs are adding plugins such as autoprefixer that the integration would also add.

[at-the-vr]

Going on a different tangent -> once tailwind v4 comes out of alpha, a lot of this dependencies will be reduced significantly. Instead of updating docs to include the postcss plugins(and eventually removing then because v4 release), how about an article that can be included in Guides ?

[sarah11918]

Thanks for such a thorough explanation here, @firxworx !

I agree that undocumented automagic stuff should definitely get into a docs page. But it seems like there are two things happening in this issue, so let's figure out how to best address each one!

Obviously, the docs repo can only... document things! 😄 We want to document as well as we can how things currently work*. To hear you say that you found a better experience not using the @astrojs/tailwind integration at all is something that should definitely be taken up with our platform devs.

My first thought was, "Oh, we can have a guide about setting up Tailwind yourself!" but then I realized, this is what the integration is for, so maybe the integration needs improving!

Would you be willing to submit some feedback regarding the integration itself, not to docs, but to the devs to see if there's a way we could be improving the integration rather than running around it? One immediate place for comments like this is the #feedback-ideas channel in our Discord. I think it's perfectly valid to say, "I have a one-liner in my config that seems to be better than the integration... and that seems wrong. How can we make the integration a better experience than not having the integration?" 😄

Separately, documenting the integration as it exists is our concern here, and we'd like that to be as helpful to the readers as possible.

So, I'm going to put "help wanted" on this issue and it can be you, and/or other members of the community starting from your great observations about what's currently not well surfaced in docs, but let's see if we can agree here in this issue what is missing from the current documentation and make a rough plan so that it will be easy to guide someone into making a PR with improvements.