v4 third party plugins

[skttl]

Congratulations on getting v4 out!

I am missing documentation for creating third party plugins in the docs (v3: https://v3.tailwindcss.com/docs/plugins).

Is this not supported anymore?

[wongjn]

You should be able to do most things in a CSS file now, with new at-rules like @utility, @custom-variant, etc. For existing v3 plugins, you can include them via the @plugin at-rule.

[skttl]

Thanks

So, if I want to be able to share a plugin like on npm, it has to be in the v3 format?

[wongjn]

You can have it as a CSS file and consumers can @import it in their own CSS.

[skttl]

Thanks, the new at-rules looks great - need to play around with them :)

[browner12]

I see the container queries have been pulled in to the main codebase. What is the status of the other 3 (typography, forms, and aspect-ratio). Should those still be pulled in via the @plugin if you need them?

[stijns96]

For those who use prettier, add /* prettier-ignore */ above it.

Did you find a way to prevent it from removing the trailing semicolon? 😩

Nope..

[manuel3108]

Since the @plugin trick should only be used for "legacy" plugins according to the docs, what is the expected way to go forward?

Will those plugins be included into the core at some point? Or are the docs misstating that this is a legacy feature? I'm not quite understanding what the current plan is, so I would be happy if anyone can elaborate.

[m6io]

I came to ask the same question as @manuel3108

[wongjn]

I believe the expectation is that plugins are now CSS files that have @utility and/or @custom-variant to do plugin things.

[manuel3108]

Do I understand that correctly, that the forms and typography will therefore be updated to support the new syntax?

Background: we are currently updating the svelte project scaffolding tool sv to support tailwindcss@4. Previously users had the possibility to select which of those 3 plugins they wanted to use and we integrated them for the user. Therefore I'm currently trying to understand if we need to keep that prompt, and which source code should be generated in that case.

As of my understanding as of now, using the "legacy" @plugin syntax is the de-facto standard for those two forms and typography plugins as of today. If my conclusion is wrong, please let me know!

[acalvino4]

Plugins could definitely use better documentation in v4, if only to say explicitly that they are being replaced by the @utility directive and .css files. As it stands, it is not clear to me whether that will cover all use cases that js plugins used to, and whether that means that @plugin will be deprecated at some point in the future. (Between the release statement, migration guide, and docs, the only mention of this atm seems to be the note that the @plugin directive is present for legacy plugins.)

As some examples, I noticed that daisyui and iconify plugins are still using this "legacy" method, and while i haven't done extensive work developing tw plugins, I have a hard time seeing how these plugins could be reimplemented using just @utility and css. If that is correct, it would seem that js plugins shouldn't be considered a "legacy" feature and that the docs should instead try to outline when you might want to use just css vs actually developing a plugin.

[stijns96]

I'm also really curious about this. There is an open issue for TW Fluid to support TW 4, but I really don't see how this could be developed without js. @wongjn could you please come back on this as I think the meed for clarifacation becomes bigger and bigger.

CSS becomes more powerfull, but JS is much more powerfull

[wongjn]

This is something for the maintainers to comment on really. I've still seen them recommend the JavaScript API in some instances, for example: #17460 (comment).

[acalvino4]

When v4 first came out, I found the lack of good plugin docs an annoying oversight, but forgivable given the otherwise awesome evolution of the framework - but it's now been out for 9 months, so I'm beginning to find it a bit more concerning. Does the team intend to support plugins as a first-class feature, or are they just an afterthought that covers a few trivial non-core cases but not much else? Are js (so called "legacy") plugins going to be deprecated at some point? If so, will there be another way to do everything they do? Currently it's anyone's best guess.

v3 had a full page documenting how to do various things via a plugin. v4 has only a small section on adding custom utilities, and a note that the @plugin directive still works but is "legacy". A few other details can be gleaned from github threads like this, but that really shouldn't be necessary.

Some of the questions that need answering in the docs are:

• What is a Tailwind v4 plugin? (a js file? a css file? sometimes one and sometimes the other? an obsolete concept?)
• Why are js files considered legacy if they are still the only way to do certain things? (to me it seems that either they shouldn't be, or there should be an outline of how the likes of iconify and daisyui will eventually be able to work as pure css plugins)
• How, via a plugin, would I
  • Override base layer styles?
  • Disable certain utilities?
  • Override certain utilities? (maybe just disable, then redefine, assuming 'how to disable' gets an answer?)
• How could a css plugin register and consume its own custom options? (see v3 analog)
• How do I publish a css tw plugin as a distributable npm package?
• How do I consume a tw plugin from an npm package in a css tw config file?

@philipp-spiess perhaps you could weigh in here? not necessarily to provide answers to all these questions, which I realize you might not have, but at least to update the community and then prioritize a docs update with the team.

[rozsazoltan]

In my personal view, I can answer your questions, but don't take this as an official position or anything like that. Due to my work, I had to closely follow the migration to v4 and monitor every step, so I can draw conclusions from that and perhaps give you a clearer picture of how plugins work in v4.

What may initially seem difficult and undocumented is actually not complicated, and the wheel hasn't been reinvented. Many developers no longer need plugins because they can create their own variants or utilities using the new directives without any plugins. But plugins still exist and remain almost untouched.

Answers (in my personal view)

What is a Tailwind v4 plugin? (a js file? a css file? sometimes one and sometimes the other? an obsolete concept?)

It's specifically a JS file, just like in v3 - you can use it with @plugin.

Many people confuse this and mistakenly call "components" that are shipped as dependencies "plugins". But those are simply components built on top of TailwindCSS utilities and configuration. Starting from v4, the configuration for components is shipped in CSS, which can be imported the same way. In such cases, there's no need to import TailwindCSS within the dependency’s CSS - that's always the responsibility of the final project. (Explained in the link below.)

Why are js files considered legacy if they are still the only way to do certain things? (to me it seems that either they shouldn't be, or there should be an outline of how the likes of iconify and daisyui will eventually be able to work as pure css plugins)

I think I'll continue my previous line of thought - components generally don't need a plugin. However, DaisyUI (since it was mentioned as an example) doesn't actually ship components; instead, it provides CSS, which it makes customizable through @plugin.

I think it's hard to answer the "why" here, since @plugin allows for quite a lot - and after all, why not? It gives you complete freedom to decide what and how you inject into your generated CSS via JavaScript.

How, via a plugin, would I override base layer styles?

I think the plugin isn't really meant for that purpose, but you can do it if you properly inject the CSS into the code through the plugin.

I think when talking about TailwindCSS, we shouldn't really be talking about base styles, since TailwindCSS truly shines through utilities applied inline in the HTML - for example, when used alongside a framework so the component can be reusable. But that's just my personal opinion.

How, via a plugin, would I disable certain utilities?

Why would you want to do that? I don't really understand. You mean applying a plugin that removes something like the bg-* utility? I don’t see the point in disabling it. Overriding or extending it is possible, though - and you can even do that with @utility.

In a CSS-first configuration, for example, colors (--color-*: initial;) can be disabled - but I think that's something that should be decided on a per-project basis, not by a plugin making that decision externally. I think if your plugin needed this, for example, it should be an installation step with a proper explanation: yes, attach my plugin with @plugin, then disable all colors in @theme because... and declare your own colors because...

How, via a plugin, would I override certain utilities? (maybe just disable, then redefine, assuming 'how do disable' gets an answer?)

As I mentioned, disabling is tricky because it adds duplicate CSS to the generated output. Redefining is similar, unfortunately, though there are cases where it can work. I think in many situations it doesn't make sense to touch existing utilities, and for the ones that do, a discussion can quickly open up so we can deliberate.

Some related posts:

• When overriding `flex-1`, two utilities are generated in the output #18944
• Combining multiple utilities to avoid code duplication; attaching a prefix to --value due to utility name shortening
• The bg-opacity-* utility no longer exists as of v4 - how could it still be created?
• Why not working {min-,max-,}w-screen-{breakpoint} following the pattern of {min-,max-,}w-{container_breakpoint}

How could a css plugin register and consume its own custom options? (see v3 analog)

I think it's the same? I haven't tested it. It's easier to answer with a concrete example. Maybe related:

• Tailwind CSS v4 - Importing JSON colors into @theme variables

How do I publish a css tw plugin as a distributable npm package?

As before, the plugin itself should be "main" in package.json. I think it's worth studying a few existing extensions for this, but the question itself is good, because a starter kit could indeed be very useful.

• https://github.com/tailwindlabs/tailwindcss-typography
• https://github.com/tailwindlabs/tailwindcss-typography/blob/main/package.json#L5
• https://github.com/tailwindlabs/tailwindcss-typography/blob/main/src/index.js

How do I consume a tw plugin from an npm package in a css tw config file?

With using @plugin in CSS-first configuration.

Plugins

By the way, the presence of @custom-variant and @utility greatly reduces the importance of plugins. For example, even the official Typography plugin doesn't necessarily need to be considered essential anymore.

Any JS file can be treated as a plugin using @plugin. Here's an example (it's admittedly poorly documented for now, but not difficult to grasp):

• Tailwind CSS v4 - Importing JSON colors into @theme variables

Note: If you publish it as an npm package, make sure the package.json points to the plugin via index.js. Then you can simply reference it in @plugin using the package name.

And I've already summarized all the existing parameterization types earlier:

• How can I pass parameters to a TailwindCSS plugin in a CSS-first configuration?

A great example of this is DaisyUI, which injects its own styles into TailwindCSS through a plugin:

• https://github.com/saadeghi/daisyui/blob/master/packages/daisyui/index.js
• https://daisyui.com/docs/install

Component packages with TailwindCSS utilities

And many people confuse the concepts of a plugin and an extension configuration. For example, if you don't need external customizability, it might not be worth shipping a plugin at all - it's enough to declare your own settings in the package that provides the components. Anyone who wants to can override those in their project later. For this, @theme, @utility, and @custom-variant are perfect.

In that case, the component package doesn't even need to use TailwindCSS - in fact, it shouldn't ship any generated CSS. See:

• Adding an external source or a package from within node_modules for detection
• All components from the UI package are included in the project's generated CSS, but I don't use every component

[acalvino4]

Hi @rozsazoltan, thanks for the thoughtful and detailed response. Unfortunately, I think most of it doesn’t really get to the bottom of my concerns, as it falls into “I don’t know your use case” (fair enough, and I’ll try to outline more details below, but not really an answer), or stems from (in my view) an unhelpful high-level view of what plugins should be.

At a high level, I think the problem with the status quo starts with how we think of what plugins are, and I think even the way I posed my question earlier was misguided and stems from this current confusion. I shouldn’t have asked “what is a tailwind v4 plugin”, as I think the problem is that I already have an idea of what it should be - in most ecosystems a plugin is something like

a modular bundle of code that extends the base tool’s behavior by registering features or integrations without modifying the base system.

Plugins, as such, are often used for one-off projects or org-specific needs, but also for common use cases, and therefore benefit from being easily shareable via package registries.

When I asked “What is a Tailwind v4 plugin?….” I wasn’t asking about the @plugin directive - I was asking “What is the standard way to package, distribute, and import bundles of code that hook into tailwind to deliver modular feature sets?” It seems that it varies by what features you want to include; when you should/have to use which one is not documented clearly anywhere. Neither is the matter of “packaging, distributing, and importing” and whether it depends on the plugin implementation (css vs js). Most of your responses assume that by plugin I mean @plugin and as such don’t really answer my questions. As just one example, saying that "@utility greatly reduces the importance of plugins" is not true for what I'm concerned about, as @utility is just one mechanism by which i might extend tw in a reusable module of code, aka "a plugin".

To summarize, my true concerns are

• How should tailwind plugins (under my definition) be shared and consumed? Does it depend (for publishing or consumption) on the implementation (css vs js)
• How powerful is/will the tw plugin interface be?
• How can/should various features of that plugin interface be used?

[acalvino4]

Now, to summarize some of those features that seem unclear/lacking to me, and for which you questioned why I'd need them.

Base styles:
I really want to create a plugin that establishes a more coherent typography alignment. I have a comment in that linked issue about this, but one aspect of such a plugin would be injecting * {text-box: trim-start cap alphabetic;} into preflight.css/ the base layer. I can of course do this in a css file in my project, but to make a modular, distributable tw plugin (under my definition, not the narrow, implementation specific tw v3 meaning), there should be a standard way to do that in a plugin.

Overriding utilities:
I want to build a plugin that replaces the default tailwind spacing system with a non-linear one. Since v4, that hasn’t been possible bc tailwind's default utility comes after the one I define with @utility. See #16997 (comment)

Disabling utilities:
If it proves impossible to directly override utilities, explicitly disabling them is another option. This would also avoid the issue with overriding where we potentially get duplicate css.