@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.

[sarah11918]

Just pinging this issue for freshness! If anyone is interested in helping to improve the Tailwind documentation, please raise your hand! 😄

(Again, the only concern for documentation is documenting the integration as it currently exists.)

[sarah11918]

Noting again that if anyone interested in Tailwind wants to make improvements to the existing guide, this opportunity is still open! (Again, only adding documentation about how the current integration works if there are important topics missing that would help people use the integration.)

[firxworx]

Hi @sarah11918 -- from your earliest comment I'm not sure where to make that comment to the devs? Please forgive me; as an outsider I just see "Astro" and am not sure how roles breakdown about who maintains what or how things work organizationally behind the curtain!

@at-the-vr makes a good comment about Tailwind v4 coming out. I haven't familiarized myself too much with it but from https://tailwindcss.com/blog/tailwindcss-v4-alpha it looks like postcss will still be an option but there will also be a Vite plugin, and I can see Astro going either direction.

Any ideas on how Astro will support tailwind v4? Maybe focusing on the next big version is the way to go in terms of updating docs or tweaking the approach?

[sarah11918]

Hi @firxworx ! I'm sorry to be talking like "people know how to reach our devs" and am happy to point you in the right place for feedback!

Re that: if you're on Discord, we have a #feedback-ideas channel where you can give feedback about how features work. Right here specifically is for issues with our documentation about how things work, as they work right now, and this space doesn't really get seen by the people who might change the feature or implementation. 😄

If you're not, then all our official integrations are maintained in the core withastro/astro repo. So you can also file an issue there if you believe there's something wonky about how the Tailwind adapter works, or want to suggest changes to it.

As you've noted, Tailwind 4 is (eventually) coming out, and there will be further changes still, both to the integration and therefore also to our documentation. The core dev spaces, including Discord, their issues and open PRs, are the best places to find out what that will look like.

I know Astro Tips has guidance for using Tailwind 4 in alpha right now: https://astro-tips.dev/tips/tailwind-v4/ This maintainers of this site include some Astro maintainers, so the "Astrolicious" org behind it will also maybe have some insight into what will happen.

I honestly don't know how long to expect Tailwind 4 to be released as stable, so I'm not opposed to having our docs work well for Tailwind users right now. I am happy to guide any community members who want to improve the current documentation for the version of Tailwind most people are using!

[inwardmovement]

The thing the doc is not clear about, as far as I'm concerned, is this (https://5-0-0-beta.docs.astro.build/en/guides/integrations-guide/tailwind/#usage):

Autoprefixer is also set up automatically when working in dev mode, and for production builds, so Tailwind classes will work in older browsers.

Does this mean Autoprefixer (1) will be enabled only for Tailwind classes, or (2) will be enabled for every style asset processed by Astro project-wide? 1: in this case, if I want to import, say, Bootstrap Sass files, I would have to setup PostCSS/Autoprefixer separately, if I want Autoprefixer enabled also for Bootstrap Sass files. 2: in this case, I do not have to setup PostCSS/Autoprefixer separately because it would be redundant with the Autoprefixer automatic setup from the @astrojs/tailwind integration.

[sarah11918]

Thanks for the specific questions @inwardmovement - knowing exactly what's confusing is really helpful to us in knowing what needs improving. I will ask some of our maintainers familiar with the Tailwind integration to describe the nuance, then see what we can do about making docs more helpful!

[JusticeMatthew]

Regarding @inwardmovement specific example autoprefixer is just enabled, you can look at the readme for it (which is linked from the astro tailwind docs page) to see that it doesn't require any specific config for your chosen CSS lib, just need to add the plugin to your postcss config and off you go

There is nothing specific to tailwind that gets added for autoprefixer, it's just a plugin with an empty options object in the postcss config (tailwind gets added in the same place in the same way usually, if you are using postcss)

Additionally just installing the integration with npx astro add tailwind does not generate a post css config for me

However here is an example of autoprefixer being used in a project where I am using Astro + tailwind + postcss, note again nothing specific to tailwind for it, just an empty options object

// postcss.config.js

module.exports = {
  plugins: {
    'postcss-import': {},
    'tailwindcss/nesting': {},
    tailwindcss: {},
    autoprefixer: {},
  },
};

[JusticeMatthew]

Here is a minimal reproduction of a basic Astro project on stackblitz with nothing changed but doing npx astro add tailwind

https://stackblitz.com/edit/withastro-astro-zqa9wm?file=README.md

postcss config w/autoprefixer is not present nor was it created by the integration