[v4] Clarify browser support

[ottomated]

Tailwind v4 seems to be taking a different direction for browser support than v3, using some pretty bleeding-edge CSS features for common utilities rather than just providing APIs for them. This is fine, but requires:

1. Very obvious documentation upon release, so people upgrading are aware that their existing code will stop working on older browsers
2. Potentially, an official plugin that transpiles utilities such as transform that lightningcss does not support (Individual transforms can't get converted to compatible syntax by lightningcss #14094)
3. Potentially, said plugin being enabled by default

I think this issue will be more pervasive upon release given that v4 will support backwards compatibility for config files and might be mistakenly seen as a drop-in replacement.

[muhharuntahir]

I agree that several steps need to be taken to ensure a smooth transition for users. Here are a few key points to consider:

1. Clear and Detailed Documentation: It is crucial that the documentation accompanying the release of Tailwind v4 is clear and detailed. Users should be informed about the major changes and how they will affect their code, especially regarding support for older browsers.
2. Official Plugin for Transpilation: Developing an official plugin that can transpile utilities such as transform that are not supported by lightningcss would be highly beneficial. This will ensure that users can still utilize new features without sacrificing compatibility with older browsers.
3. Enabling the Plugin by Default: If such a plugin exists, enabling it by default would be a wise move. This will reduce the burden on users to reconfigure their projects and ensure broader compatibility without additional effort.
4. Clarification on Backwards Compatibility: It is essential to emphasize that although v4 supports backwards compatibility for configuration files, this does not mean that old code will work perfectly in all scenarios without modifications. Clear communication and guidelines should be provided to avoid this misconception.

By taking these steps, we can ensure that the transition to Tailwind v4 will be smooth and not cause significant disruptions for existing users.

[adamwathan]

Hey! The documentation and upgrade guide will definitely be clear about all of this.

We only do major versions every few years so we try to always use them as an opportunity to jump on fairly new platform features so that two or three years down the road the framework is already ready for them and we don't feel like we have to pump out a new major version every 12 months.

This was also the case with Tailwind CSS v2.0 where CSS variable support became a requirement to use the framework. A lot of people weren't totally comfortable with them yet, but now in 2024 we'd look like a framework from the stone age if we weren't taking advantage of them.

@ottomated: As you mentioned in another comment, features we're depending on have 85% audience coverage at the moment according to Browserslist:

https://browsersl.ist/#q=chrome%3E%3D111%2Cedge%3E%3D111%2Csafari%3E%3D16.4%2Cfirefox%3E%3D128%2Copera%3E%3D97%2Cchromeandroid%3E%3D127%2Csamsung%3E%3D22%2Cios%3E%3D16.4

The recommended defaults option in comparison has 88.3% coverage:

https://browsersl.ist/#q=defaults

So it's a little bit less, but I think it'll catch up a bit by the time we actually release Tailwind CSS v4.0 around ~December. I also think these numbers are maybe a bit inaccurate right now, because I'm surprised they are recommending a configuration that has < 90% coverage, which makes me think that the delta between our requirements and defaults is maybe the more important thing to track.

"Can I use…" reports 93.37% coverage for the translate property for example, but entering all those same browsers into Browserslist only reports 91% coverage:

https://browsersl.ist/#q=chrome%3E%3D104%2Cedge%3E%3D104%2Csafari%3E%3D14.1%2Cfirefox%3E%3D72%2Copera%3E%3D90%2Cchromeandroid%3E%3D127%2Csamsung%3E%3D20%2Cios%3E%3D14.1

Either way like I've already mentioned we'll be very clear about browser support when the release is ready, and for folks who can't migrate right away because they still need to support older browsers, Tailwind CSS v3 will continue to be a good choice until adoption of more modern browsers catches up.

Appreciate the feedback either way and we can always revisit some of the properties we're depending on or things we should consider trying to polyfill if our browser targets are too bleeding edge for the majority of users.

[sdavids]

@adamwathan

we'll be very clear about browser support

Unfortunately neither the migration guide nor the announcement blog mention the minimum browser support.

Maybe also mention whether it supports Baseline?

[beiatisi]

I think we need to understand the browser support, otherwise some key projects will not dare to upgrade tailwind to the latest version and experience the better experience it brings us.

[philipp-spiess]

@sdavids @beiatisi We have a page for compatibility that mentions the browser support as the first thing: https://tailwindcss.com/docs/compatibility

[sdavids]

Maybe you could add a link to that page in the migration guide to make it easier to find.

Also, you might want to:

• Instead of stating specific browser versions state that the Tailwind v4 Core is Baseline 2024 (due to CSS @property). https://web.dev/blog/show-baseline-status

• State that for the lifetime of v4 this will not change.

Should I create a new issue for these suggestions? – Considering this issue is closed?

[Soviut]

I definitely got bitten by the higher than expected compatibility requirement. All I saw was "run this npx package and you'll be automatically upgraded"; if there was a compatibility message, I didn't see it.

I'm on a project where the device I'm developing for is pinned to Chrome 87; not terribly old, but definitely out of range of the Chrome 111 (which I found after upgrading). The issue being that things like native cascading layers, OKLab colours, etc. aren't supported that far back. I tried some PostCSS plugins that at least got the site rendering with styles, but so many things were broken I had to revert it.

For projects like mine, it'll be impossible to upgrade to Tailwind 4 without some compatibility settings or a compatibility plugin. I don't mind "legacy" browsers not being the initial target, but support should make it's way backwards eventually. Chrome 87 was from late 2020 and there are potentially millions of devices still running it, meaning new tailwind sites could be breaking on them with no recourse.

[alexanderbuhler]

Just going to leave that here for anyone who dares to tinker: https://gist.github.com/alexanderbuhler/2386befd7b6b3be3695667cb5cb5e709

@Soviut what parts of your project didn't work properly? Polyfilling @property rules did the heavy lifting for me, the rest is basically minor.

[ottomated]

@alexanderbuhler #14094 is an issue too

[alexanderbuhler]

@ottomated Added this to the gist today. Appreciate you pointing that out to me!

[kerams]

Unless you have a hard requirement to support old browsers, I can recommend using !CSS.supports('color:oklch(0 0 0)') in JS to show an unsupported browser warning of some sort. That way users will at least know why the website is broken and how to proceed.

[wevertondcl]

@alexanderbuhler Have ani tip for use the Gist? tried everything to add this to my laravel 12 + tailwind v4 project, but didn't work.
I need a way to make tailwind v4 compatible with Chrome 109..

[zounar]

In my case, I have to support older browsers, but I don't want to stick with Tailwind 3 just because of it. I made two changes to the setup that improved the backwards compatibility. It's not perfect, but decent enough.

Check out this repo where I document those changes.

[wevertondcl]

In my case, I have to support older browsers, but I don't want to stick with Tailwind 3 just because of it. I made two changes to the setup that improved the backwards compatibility. It's not perfect, but decent enough.

Check out this repo where I document those changes.

Saved my life bro, thx! I was needing the compatibility with 109 version of Google Chrome!

[alexanderbuhler]

@wevertondcl My gist assumes that you have a PostCSS processing step in your build pipeline.
@zounar Good stuff! I am using https://www.npmjs.com/package/@csstools/postcss-oklab-function for conversion.