UnoCSS With Next.js & Turbopack: The Ultimate Guide
Hey everyone! Are you guys ready to dive deep into a super important topic for all you Next.js and UnoCSS fans out there? Today, we're going to talk about UnoCSS support for Next.js with Turbopack. This is a big deal because, well, it impacts how we write our code and the tools we use. We'll cover the problems, solutions, and everything in between. So, buckle up!
The UnoCSS and Turbopack Problem
Alright, let's get down to brass tacks. The main issue we're tackling is that UnoCSS transformers, specifically transformerAttributifyJsx, transformerVariantGroup, and transformerDirectives, aren't playing nice with Next.js when it's using the Turbopack bundler. This is a real bummer, because these transformers are what give us some of UnoCSS's best features. If you're coming from a Vite setup, you're likely used to these amazing features, and now you have to face the fact that these transformers will be completely ignored, which is sad, right?
For those who aren't familiar, let's break down what's being missed here. @unocss/postcss is designed to process CSS files. This means it handles things like @apply and @unocss directives, which are cool and all, but it doesn't touch your JS/TSX source code. This is where the transformers come in. They do the magic of converting your component's code to the expected styles. The lack of support from Turbopack means stuff like attributify syntax and variant groups are simply not transformed. Your code looks like it should work, but it doesn't.
Let's look at an example to help bring this home. Imagine you're using attributify syntax like this:
<div text="red" p="4" flex="~ col">Content</div>
With Turbopack and without the proper integration, this code will render without the expected styles. The text="red", p="4", and flex="~ col" attributes won't be translated into the corresponding CSS classes that UnoCSS would normally generate. Similarly, variant groups suffer the same fate. Consider this example:
<div className="hover:(bg-red text-white)">Content</div>
The hover:(bg-red text-white) part, which should apply red background and white text on hover, will be completely ignored. Next.js 15 and above is moving to Turbopack as the default, which means many users will lose this transformer functionality. It's a huge step back in terms of developer experience and efficiency, because you lose the ability to use the full power of UnoCSS with these source-level transformations.
This is a problem because Turbopack is becoming the standard. The old ways of using Vite are slowly being left behind, so it's essential for UnoCSS to adapt. Many developers have to make a choice between using the cutting-edge features of Next.js with Turbopack, or using the familiar UnoCSS transformers with Vite. This is a hard decision, because both are very important, but having both is the best option.
The impact on developers
So, what's the big deal? Why is this a problem? Well, when the transformers don't work, it limits how you can use UnoCSS. You lose the ability to write cleaner, more readable code. Attributify syntax lets you define styles directly in your HTML, which can be super convenient. Variant groups make it easy to handle responsive design and pseudo-classes (like hover, focus, etc.). Without these, you're forced to write more verbose CSS or use more traditional class names, which isn't as elegant or efficient.
This also creates a fractured developer experience. Some developers might be able to use UnoCSS with Vite, while others have to adapt and find workarounds. This inconsistency can make it harder to collaborate on projects and can slow down the development process overall.
Suggested Solutions: Getting UnoCSS and Turbopack to Play Nice
Alright, so we've established there's a problem. Now, let's talk about the good stuff – the potential solutions! The key here is to find a way to integrate UnoCSS's transformations directly into Turbopack. This means making sure the source code is processed correctly before it gets bundled.
One promising approach is for UnoCSS to provide an official Turbopack integration. Turbopack has a cool feature that allows you to create custom loaders via next.config.ts. UnoCSS could create a package like @unocss/turbopack or @unocss/next, that would take care of this integration. The goal is to make it as seamless as possible for developers, with a simple installation and configuration process.
How would this work? The integration would involve registering a Turbopack loader that handles .ts, .tsx, .js, and .jsx files. When Turbopack encounters these files, the loader would kick in. It would load the UnoCSS configuration, apply the transformers to the source code, and then pass the transformed code along. This ensures that the UnoCSS transformers are applied before the bundling process. The cool thing is, this would work alongside @unocss/postcss for generating the CSS files. So, you'd get the best of both worlds – source-level transformations and CSS generation.
Proof of Concept: A Glimmer of Hope
There's already a proof-of-concept library (turbopack-unocss-transform) that demonstrates how this integration could work. The library essentially does the steps we described above: it registers a Turbopack loader, loads the UnoCSS config, applies the transformers, and handles the source code. This shows that a solution is within reach.
Alternative Solution: SWC Plugin
Here's another option: a SWC plugin. Turbopack uses SWC (Speedy Web Compiler) under the hood. SWC is written in Rust, which means it's super fast. A Rust-based transformer, written as a SWC plugin, could potentially be even faster than the current approach. The downside? It requires expertise in Rust. This might be a bigger undertaking, but it could lead to significant performance improvements. SWC plugins would provide a direct way to hook into the compilation process and apply the UnoCSS transformations.
The Path Forward: Bringing UnoCSS and Next.js Together
To make this all a reality, the UnoCSS community needs to come together and prioritize this integration. It's a critical step to ensure that developers can continue to enjoy the power of UnoCSS with the latest Next.js features. Here’s what can be done:
- Community Support: Show your support! If you're a user of UnoCSS and Next.js, let the maintainers know how important this is to you. Open issues, contribute to discussions, and help test out any potential solutions.
- Development and Collaboration: Developers with the necessary skills (especially those with experience in Turbopack, SWC, or Rust) can contribute to building these integrations. This could involve creating packages like
@unocss/turbopackor developing a SWC plugin. - Documentation and Education: Once the integration is ready, we'll need clear, concise documentation and examples. This will help developers get up and running quickly. Tutorial videos, blog posts, and other educational resources will be invaluable.
Next Steps
The most important thing right now is to keep the conversation going, spread the word and test out any potential solutions. The UnoCSS team has been doing an amazing job, so we can be sure this will be implemented in the best possible way.
Conclusion: The Future is Bright
So, there you have it, folks! We've covered the issue of UnoCSS and Turbopack, discussed potential solutions, and outlined the steps to make it happen. This is a significant problem that needs to be addressed to improve the developer experience of all the users, and I hope we can find an elegant solution. The good news is, there are solutions on the horizon, and with the community's help, we can make sure UnoCSS continues to thrive with the latest and greatest features of Next.js.
Remember, if you're experiencing this issue, let your voice be heard! The more awareness we raise, the faster we'll see a solution. Let's work together to make the web a better place, one line of code at a time! Thanks for reading, and happy coding!