This is the user manual for the twind library. A small compiler that turns Tailwind short hand into CSS rules at run, build or serve time. If you have used Tailwind and/or a CSS-in-JS solution before then most of the API will feel very familiar.
We are confident that feature parity with Tailwind V2 has been achieved. We recommend you refer the Tailwind documentation site for anything non twind implementation specific; information around directives, variants, theming etc.
If you find any incorrect or missing documentation then please open an issue for discussion.
- Installation - how to install
twindor applytwind/shim - Setup - how to use
setup - Theming - how to apply your theme
- Examples - how to integrate with different frameworks
twFunction - how to usetw- Grouping - how to optimize rules size
- Tailwind Extensions - which additional features are available
- CSS-in-JS - how to apply custom css
- Plugins - how to extend twind
- Testing - how to verify the generated class names
- Static Extraction (SSR) - how to extract the generated css on the server
If you would like to get started with twind right away then copy paste this code into your favorite sandbox.
import { tw } from 'https://cdn.skypack.dev/twind'
document.body.innerHTML = `
<main class="${tw`h-screen bg-purple-400 flex items-center justify-center`}">
<h1 class="${tw`font-bold text(center 5xl white sm:gray-800 md:pink-700)`}">This is Twind!</h1>
</main>
`Alternatively try the live and interactive demo.
For seamless integration with existing Tailwind HTML you can use twind/shim:
<script type="module" src="https://cdn.skypack.dev/twind/shim"></script>
<main class="h-screen bg-purple-400 flex items-center justify-center">
<h1 class="font-bold text(center 5xl white sm:gray-800 md:pink-700)">This is Twind!</h1>
</main>Try twind/shim in the live and interactive shim demo
Check out this extended demo
The core problems we are trying to solve here are as follows:
- Parsing Input: taking input and normalizing it to create a comprehendable set of Tailwind rules
- Compiling Rules: taking a set of Tailwind rules and translating them into appropriate CSS rules
- Injecting Styles: taking CSS rules and generating classes that get append to a stylesheet in the DOM
- Merging Themes: combining JSON themes which configure and constrain the compiler
- Custom Plugins: taking functions and using them to extend the capabilities of the compiler
This has to happen in a performant way at runtime, whilst adhering to Tailwind V2 as a language specification. All grammars that exist in Tailwind should be covered by this implementation.
Simply recreating a tailwind like experience at runtime might seem like a futile exercise but we'd like to believe it opens up the doors to some exciting new possibilities. There is always going to be a tradeoff between compiling at ahead of time and compiling just in time, however we are confident the upsides here are significant enough to persue a runtime implementation and the results have been promising so far.
Note it is still possible to remove all runtime overhead via a prepass either at serve or built time
The flexible nature of a runtime first approach affords us possibilities like:
- Dynamic Theming: generating new themes on the fly without the need to rebuilding anything
- Unlimited Variants: enabling every variant combination by default because unused rules are never generated
- Enhanced Syntax: taking advantage of macros within template literals to create more terse rules
- Error Handling: warning the developer about unknown directives and theme values
- Hashing Classes: reducing the overall output size and eliminating conflicts via deterministic hashing
- Inline Plugins: extending the capabilities of the compiler with simple functions at runtime
Another big advantage we see of shipping the interpreter compiler itself (rather than pre-compiled output) is that the effective size of the CSS for your whole app is deterministic and fixed. The weight of the compiler itself along with your theme file is all that users will ever download, no matter how many styles you use.
Currently the compiler weighs around 10KB which is smaller than styled-components and the average tailwind output.
It goes without saying that the primary inspiration here comes from Tailwind. It is a revolutionary take on styling the web which has proven popular by designers and developers alike. All the core plugins here, abide by the rules painstakingly thought out, implemented and popularized by Adam Wathan et al. making us forever in his debt.
We hope one day we will get the chance to collaborate with Tailwind Labs to create an official implementation!
Continue to Installation