RFC: Tailwind Support

[timneutkens]

Edit: #20030 (comment)

Goals

• Backwards Compatible. Does not affect existing Tailwind users
• Zero config. No need for postcss.config.js and auto-inject TailwindCSS
• High performance. Purging configured out of the box
• Optimal DX. Fast refresh integration with no compilation slowdowns
• No compilation impact until used. Zero impact to applications that don't want to use Tailwind

Background

Utility-first CSS is gaining a lot of adoption over the past few months. This is especially driven by the rise in usage of the Tailwind CSS framework. One of the most useful things about using Tailwind in comparison to other CSS frameworks is that it tree shakes itself away as much as possible, meaning it exposes a lot of classes but only the ones that you use will be bundled into the production CSS file, giving you a small CSS bundle compared to writing all styles yourself.

Setting up Tailwind takes quite a few steps:

• You need to create a pages/_app.js that imports a stylesheet.
  • This stylesheet then has to use @tailwind directives to inject the Tailwind styles.
  • There's some compilation burden when improperly set up, causing recompilation of CSS to take significantly longer than expected.
• You need to create a postcss.config.js and include tailwindcss and all the PostCSS plugins Next.js has by default.

Given the rise in usage, it makes sense for Next.js to make this setup simpler.

Resources:

• To learn more about utility-first CSS: https://www.youtube.com/watch?v=R50q4NES6Iw
• To learn more about Tailwind: https://tailwindcss.com
• Official guide for Next.js + Tailwind: https://tailwindcss.com/docs/guides/nextjs

Implementation

• When Next.js detects a tailwind.config.js it automatically sets up Tailwind for you
  • This effectively makes the setup running npm install tailwindcss and then npx tailwindcss init.
  • Because existing applications using Tailwind should not be affected by this change we will disable the built-in Tailwind support when a postcss.config.js is added (this is currently required to set up Tailwind correctly so it's a good measure to prevent breaking).
• The required Tailwind CSS file is automatically imported, so no custom setup is required.

[browniefed]

There are other systems like https://github.com/Arthie/xwind and (maybe?) https://github.com/ben-rogerson/twin.macro where a tailwind config exists but things are all processed very differently through a CSS-in-JS solution.

Would the "auto-enable" increase any sort of bundle sizes at the mere detection of a tailwind config? Is there a way to opt-out?

[timneutkens]

We can automatically opt-out for those cases

[Arthie]

Hey, I'm the maintainer of xwind feel free to reach out if u need any help/feedback with the opt-out.

For those wondering what the difference is in approach between Tailwind and xwind:

Tailwind approach:

1. generate a big CSS file
2. analyze the big CSS file and project source files to get the used tailwind classes (using string matching = not perfect)
3. remove unused CSS

xwind approach:

1. transpile project source files to get the used tailwind classes (using custom syntax = perfect matching)
2. generate the minimal CSS file or a different output from used tailwind classes

One of the advantages of xwind's approach is the possibility to configure the output to your preferred CSS solution:

• minimal CSS file
• object styles for CSS-in-JS
• CSS modules
• React Native styles
• Route/component based CSS generation for code splitting
• ... (it's basically a compiler so anything is possible)

[cweekly]

Very interested in tw + twin.macro + (emotion with sx prop) ...

[markozxuu]

Everything sounds great. What will be the strategy so that this integration does not increase the weight of the next package ? 🤔

[Skn0tt]

Is the weight of the next package considered a problem? The tailwind integration code wouldn't be sent to the frontend anyway, right? :)

[timneutkens]

As said in the RFC you have to manually install tailwind into your project so it does not impact Next.js' size.

Is the weight of the next package considered a problem?

Overall we try to optimize the package size as much as possible to ensure the package installs faster.

[alevosia]

Low on storage space?

[pdevito3]

This is awesome! How will next handle custom @tailwind files where we want to make customizations like @apply or custom css?

Sounds like it will just assume the default base, components, and utilities setup behind the and if we want to customize it we make and import the file(s) as normal?

[laSinteZ]

Will this support only Tailwind 2, or Tailwind 1 included? (Since Tailwind 2 doesn't support IE11, this is kinda important.)

[programbo]

AFAIK there’s no PostCSS config difference between v1 and v2 and the presence of a Tailwind config file isn’t dependent on a particular version of Tailwind.

[pdevito3]

It will probably install latest, but you could change package.json to 1.9.6 if you want. Everything else should operate the same.

[programbo]

• This effectively makes the setup running npm install tailwindcss and then npx tailwindcss init.

Installing your desired version of tailwindcss is still being suggested at the first step.

[vvo]

Would you support/what about supporting styled-jsx @apply rules too?

I managed to get it working via https://github.com/giuseppeg/styled-jsx-plugin-postcss

And now I can write things like:

 <style jsx>{`
  div[aria-selected="true"] {
    @apply text-white bg-indigo-500;
  }
}</style>

Which is very handy in situations where nor className= nor style= are sufficient and you still want to use tailwind classes

[DaniGuardiola]

You can always use CSS modules, but I agree the flexibility of styled-jsx comes in handy sometimes.

[timneutkens]

Not planning on it currently.

[vvo]

You can always use CSS modules, but I agree the flexibility of styled-jsx comes in handy sometimes.

Hi @DaniGuardiola, can you use @apply in CSS modules? Any configuration needed? Seems interesting indeed instead of styled-jsx in this case.

[justincy]

@vvo I know it's possible because I did it once, but I can't recall whether it requires any additional config beyond what's already required for Tailwind.

[giovannibenussi]

Maybe a bit out of scope, but what about a command that setups everything for you:

• Install tailwind
• Create an optimized tailwind.config.js file (e.g: with the purge option enabled)

Something like yarn next setup tailwind

[DaniGuardiola]

Well, I don't think there'd be much of an advantage, and this way it's consistent with, for example, how you setup TypeScript.

[botv]

Tailwind has a pretty thorough guide on how to add TailwindCSS to a Next.js app, it pretty much already is just one command, after the installations.

[amiralies]

What about amp support?
We can use same bundle output in amp pages but using whole application css may hit the amp css size limit. can we somehow extract css for amp pages , page by page?

[msurdi]

How would purging work in this case? By looking into directories such as components and pages and "grepping" as it is done (as I understand it) with purge-css? Or by analyzing actual imported components? Would it be possible to detect classes used (and thus not purging them) in, for example, an imported component from a shared library let's say in node_modules/my-design-system/lib/Button.jsx?

Thanks!

[joshmanders]

Purging is done through Tailwind itself and the tailwind.config.js file. This is independent of Next. You can read more here: https://tailwindcss.com/docs/optimizing-for-production

[jgb-solutions]

How to use@apply in this case?

[antoinegag]

I assume all CSS files will be processed through PostCSS and @applys will be handled then by the tailwind plugin ?

[l4u]

Does it include https://github.com/tailwindlabs/headlessui support?

[joshmanders]

Headless UI is not dependent on Tailwind at all

[jon-eckstein]

Would this work with SSR? Can it collect styles in the same way that MUI and StyledComponents do with ServerStyleSheets?

[leodr]

Tailwind always works with SSR because it creates a plain old CSS stylesheet at build time. No fancy JS runtime thing.

[jon-eckstein]

Ah ok, makes sense, thanks @leodr

[soilSpoon]

You can use https://github.com/ben-rogerson/twin.macro.

[okbytes]

Does Next.js's code splitting work on Tailwind today? If not, that would be wonderful first-party support to get Tailwind's size down even more.

[leerob]

Let's make sure Tailwind support can handle very large files w/ dark mode in a memory-efficient way (related #21529).

Edit: Sovled! See below.

[jensmeindertsma]

Will @tailwindcss/jit help solve this problem?

[leerob]

Yep - we can consider this solved 😄

[merodiro]

What about recipes like in blitz that handles tailwind setup? it is completely opt-in and won't affect who don't use it

https://github.com/blitz-js/blitz/tree/canary/recipes

[DaniGuardiola]

Just leaving this here... https://github.com/tailwindlabs/tailwindcss-jit

[leerob]

Hey y'all! There's been many updates since we first announced this RFC:

• Tailwind JIT Compiler: v3 made the JIT compiler the default, which compiles your CSS on-demand versus generating the entire stylesheet up front.
• Tailwind Zero-Config: v4 is coming soon with many incredible improvements, including not needing to use configuration files and faster performance.
• Create Next App Improvements: npx create-next-app@latest now includes an option to use Tailwind, on by default.

Since the original goals have been satisfied with improvements to Tailwind and further improvements coming with v4, we are going to close this RFC. Thank you all for the feedback and excitement.