twust_macro 1.1.0

Zero-config Static type-checker for Tailwind CSS
Documentation

twust

Twust is a powerful static checker in Rust for TailwindCSS class names at compile-time. It ensures correctness by validating class names before runtime, preventing errors and improving developer experience.

Features

  • Compile-time validation of Tailwind CSS class names. Prevents typos and invalid Tailwind class names.
  • No runtime overhead – errors are caught at compile time.
  • Supports single and multiple class formats.
  • Supports DaisyU under a feature flag.
  • Configurable: Supports overriding, extending, custom classes, custom modifiers, Plugins and many more.
  • Flexible macro-based API.
  • Returns class names as a string or an array for easy use in UI frameworks.
  • Works seamlessly in Rust UI frameworks like Leptos, Dioxus, Yew, and Sycamore.
  • Lightweight and blazing fast!

Installation

[dependencies]
twust = "1.0.7"

Enable optional features (e.g., daisyui support):

[dependencies]
twust = { version = "1.0.7", features = ["daisyui"] }

Usage

tw! - Compile-time Type-Checked Tailwind Classes

use twust::tw;

let class = tw!("bg-red-500 text-lg");
assert_eq!(class, "bg-red-500 text-lg");

// You can also separate classnames by space, these will be merged
let classes_list = tw!["bg-blue-500 hover:bg-blue-700", "bg-purple", "py-sm md:py-md tablet:py-sm lg:py-lg xl:py-xl"];
assert_eq!(classes_list, "bg-blue-500 hover:bg-blue-700 bg-purple py-sm md:py-md tablet:py-sm lg:py-lg xl:py-xl")

    // You can override/extend color/background color in tailwind.config.json
tw!("bg-taxvhiti bg-tahiti-500 bg-tahiti bg-midnight bg-purple bg-red-50 bg-tahiti-800 border-s-tahiti-800");
tw!("md:text-red-50 text-slate-50 text-purple text-tahiti-500");
tw!("py-sm md:py-md tablet:py-sm lg:py-lg xl:py-xl");
tw!("group");
tw!("hover:-translate-y-0.5 transition motion-reduce:hover:translate-y-0 motion-reduce:transition-none");
tw!("group/edit block invisible md:hover:bg-slate-200 group-hover/item:visible");
tw!("group-[:nth-of-type(3)_&]:block group-hover/edit:text-gray-700 group-[:nth-of-type(3)_&]:block");
tw!("scroll-m-15 group-aria-[sort=ascending]:rotate-0");

// Even scroll margin can also be configured, here we add, sm and md under the Spacing/scrollMargin field in the config file
tw!("scroll-mx-sm scroll-mx-md");
tw!("px-[-45px] px-[-45cm] px-[-45rem] px-[-45em] px-[-45%] px-[-45vh]");
tw!("m-4 last:first:invalid:last:first:p-4 last:m-4 pb-[calc(100%-34px)] pb-[23px] [mask-type:luminance]
    [mask-type:luminance] hover:[mask-type:alpha] lg:[--scroll-offset:44px] oyelowo oyedayo break-after-avoid"
);
tw!("h-full border-2 border-opacity-60 rounded-lg overflow-hidden");

tws! - Compile-time Checked Array of Classes

use twust::tws;

let class_list = tws!["bg-red-500", "text-lg", "p-4"];
assert_eq!(class_list, ["bg-red-500", "text-lg", "p-4"]);

tw1! - Single Tailwind Class Only

use twust::tw1;

let class = tw1!("bg-red-500");
assert_eq!(class, "bg-red-500");

tws1! - Array of Single-Class Items Only

use twust::tws1;

let class_list = tws1!["text-xl", "border", "m-4"];
assert_eq!(class_list, ["text-xl", "border", "m-4"]);

tailwind.config.json Overview

Basic Structure:

{
  "corePlugins": {},
  "allowedLists": {
    "classes": [],
    "modifiers": []
  },
  "theme": {
    "extend": {}
  },
  "variants": {},
  "plugins": {}
}

Statement of Problem

TailwindCSS offers developers a flexible utility-first approach to styling web applications. However, its flexibility can also lead to potential pitfalls:

  • Runtime Errors: Invalid TailwindCSS class names can cause unexpected styling issues that are only caught during runtime.
  • Developer Experience: Manually validating class names can be tedious and error-prone.
  • Plugin Compatibility: Some TailwindCSS utilities extend their functionality with plugins like DaisyUI, which traditional methods might not support.
  • Increased Build Size: Invalid class names that slip into the production code can increase the final CSS bundle size.

Solution

Twust addresses these challenges by offering:

  • Compile-time Validation: Ensures that only valid TailwindCSS class names are used, preventing errors in production.
  • Seamless Integration: Works within Rust macros for an improved developer experience.
  • Plugin Support: Easily integrate popular plugins like DaisyUI with feature flags.
  • Optimized Builds: Reduces unnecessary CSS bloat.

How does this compare with Other Rust Libraries?

tailwindcss-to-rust

  • Requires complex setup and external dependencies.
  • Generates Rust code that must be maintained manually.
  • Lacks full support for all Tailwind utilities.

twust

  • No setup required – just use the macros.
  • Works in real-time at compile-time.
  • Self-contained with no external dependencies.
  • Supports all standard TailwindCSS class names, including responsive variants.

License

Twust is licensed under MIT/Apache-2.0. See LICENSE for details.

© Oyelowo Oyedayo

Email: oyelowo.oss@gmail.com

⭐ Show Some Love!

If you find Twust useful, give it a ⭐ on GitHub!