Documentation for JavaScript Plugins

[jsudelko]

I'm extremely frustrated by the lack of mention of JavaScript plugins in the Tailwind V4 documentation.

I think not providing documentation has the reverse effect of what the Tailwind team intended. This vague comment is the only form communication I've found from the Tailwind team from searching on GitHub and the Tailwind website. It seems the hope was that people would not shoot themselves in the foot by creating new JavaScript plugins for performance reasons, without actually recognizing that most tailwind plugins have already been written and are now stuck in Tailwind V3 with no official guidance on a way forward. Just as importantly, the knowledge that people have in their heads (and references on the internet) is from V3. It's a Python V2 to V3 or Node CJS to ESM situation now happening in Tailwind.

Because the V3 API is still supported, it should be documented, even if it's with a large "DEPRECATED: DO NOT USE THIS" banner. It should ideally include "Migrate like this" (LLM friendly) instructions for each hook/API. The goal should be incremental adoption.

The documentation for existing CSS APIs are clearly targeted at Tailwind end users, but there should be something targeted specifically at people creating plugins for others to consume.

It's worth addressing explicitly your intention for JavaScript plugins. e.g. is the intention to drop JavaScript plugins entirely (e.g. in Tailwind v5)? If you're still of the stance that people will shoot themselves in the foot, you could make it only discoverable by search such that existing users who know what to look for can find them.

While the Tailwind V3 docs for plugins were unfortunately quite scarce, you could at least read through official TW plugins and other popular plugins to see patterns they discovered. They're all mostly still using V3 APIs, so it's not clear how to implement the same functionality for external plugin consumers using the new CSS APIs. As @philipp-spiess mentioned in the linked comment, I'd appreciate if the team prioritized migrating the existing official plugins (or provide demo plugins if that's easier) so that we can have a reference when documentation fails.

For now, I'm implementing a V3 plugin at a performance cost because it's what I (and LLMs!) know, what the official plugins do, and there's no guidance otherwise. I will migrate once there are better references and documentation.

[jsudelko]

I finally figured out how to map all of the V3 JS APIs I'd been using after a few hours of playing with the CSS APIs in a small playground. It's actually quite easy once you understand how inputs of the custom Tailwind syntax maps to outputs. If I was explaining it to myself from a few hours ago, I swear it would have taken me 20 minutes instead.

Not documenting the JS APIs in fear of foot-gunning was the wrong decision by the Tailwind team.