Crate encre_css

A TailwindCSS-compatible utility-first CSS generation library written in Rust.

A brief introduction to utility-first CSS frameworks

Traditionally, whenever you need to style something on the web, you write CSS in a dedicated file and apply the rules using classes in your HTML, like that:

A new Javascript library has been released!

The library react has just been released, did you know it? It is a JavaScript library for creating user interfaces.

Dismiss Try it here!

<div class="notification">
  <div class="notification-header">
    <div class="app-icon"></div>
    A new Javascript library has been released!
  </div>
  <div class="notification-body">
    The library <code>react</code> has just been released, did you know it?
    It is <i>a JavaScript library for creating user interfaces</i>.
  </div>
  <div class="notification-footer">
    <a href="#" class="dismiss-button">Dismiss</a>
    <a href="#" class="try-button">Try it here!</a>
  </div>
</div>

However styling this way is pretty boring because you need to think of good class names and you have to repeatedly switch between several files, it could be better. Utility-first CSS frameworks takes a new approach by using minimal and pre-defined class names directly linked to its CSS rule content. The CSS file will then be generated on-demand allowing the classes to be very flexible and customizable. This approach lets you quickly prototype visual HTML elements and encourages you to turn them later into components using your favorite web framework. It also makes building a responsive website easier and forces it to be closer to your design system:

<div class="w-128 text-md shadow-[1px_1px_10px_2px_#e5e7eb] rounded-xl">
  <div class="p-3 flex items-center">
    <div class="bg-blue-500 rounded-full w-5 h-5 mr-3"></div>
    A new Javascript library has been released!
  </div>
  <div class="p-6 pt-4">
    The library <code>react</code> has just been released, did you know it?
    It is <i>a JavaScript library for creating user interfaces</i>.
  </div>
  <div class="flex justify-between">
    <a href="#" class="p-3 text-rose-600">Dismiss</a>
    <a href="#" class="p-3 bg-blue-600 text-white rounded-br-xl rounded-tl-xl shadow shadow-blue-600">Try it here!</a>
  </div>
</div>

There is already a lot of utility-first frameworks like Tailwind CSS, Windi CSS, Twind and Uno CSS, but encre-css is unique because it is written in Rust and uses a new architecture, making it the fastest utility-first framework (according to the benchmark here based on Uno CSS’ benchmark). It is also very customizable.

Getting started

Add encre-css to your Cargo.toml:

[dependencies]
encre-css = "0.14.1"

Generating styles takes two steps:

• You need to configure the CSS generation by making a Config structure. It can be created by reading a TOML file using Config::from_file or by using the default values with Config::default;
• Then, you need to generate the styles based on some sources using the generate function. This function will scan the content of the sources, extract atomic classes and generate the style needed for each class.

Example

use encre_css::Config;

let config = Config::default();
let generated = encre_css::generate(
    [r#"<p class="w-auto bg-red-200 rounded-md">Hello world!</p>"#],
    &config,
);

assert!(generated.ends_with(".w-auto {
  width: auto;
}

.rounded-md {
  border-radius: 0.375rem;
}

.bg-red-200 {
  --en-bg-opacity: 1;
  background-color: rgb(254 202 202 / var(--en-bg-opacity));
}"));

What to do next

1. The documentation about the composition of a class (also named selector) is here.
2. The documentation about all utility classes (handled by plugins) is here.
3. The documentation about the reset CSS commonly used (also named preflight) is here.

Command line interface

A command line interface is also available. Install it using:

cargo install encre-css-cli

Then run encrecss --help for instructions on how to use it.

Modules

• config
  Define the Config structure used to configure the generate function using a Tailwind-like configuration.
• error
  Define a custom Error type.
• generator
  Define the main generate function used to scan content and to generate CSS styles.
• plugins
  A Plugin is a handler used to convert utility classes into CSS declarations.
• preflight
  Define the default set of base CSS styles used to make websites consistent across browsers.
• prelude
  Various helper preludes.
• scanner
  Define a structure used to scan content.
• selector
  Define the structures used to parse scanned classes.
• utils
  Define some utility functions for quickly doing things.

Macros

• toml
  Construct a Table from TOML syntax.

Structs

• Config
  The configuration of the CSS generation done in the generate function.
• Scanner
  A structure responsible for scanning some content and returning a list of possible classes.

Enums

• Error
  The custom error type used everywhere in this crate
• Preflight
  The set of default styles.

Functions

• generate
  Generate the CSS styles needed based on the given sources.

Type Aliases

• Result
  Shorthand for Result type.