Introduction

Compiler DSL for CSS in Abstraction

Unlike typical CSS-in-JS solutions that ship runtime code in the bundle, Plumeria operates entirely at compile time. It resolves styling purely through type definitions and plugins, with no JavaScript remaining at runtime.

package.json

{
  "name": "@plumeria/core",
  "exports": {
    ".": {
      "types": "./lib/css.d.ts",
    },
  },
}

Plumeria has no runtime evaluation. Except for dynamic styling with function keys and when receiving props for variants, styleName only resolves static styling. This guarantees that all APIs are compiled only into static class names and CSS.

Strictly no JavaScript

Styling shouldn't require any runtime. By treating styles as type schemas instead of runtime objects:

No runtime bundle
No runtime evaluation
No runtime parsing
No runtime dependencies

The concept of Zero-Runtime

A library that is entirely Zero-Runtime doesn't truly exist. Even pure CSS will experience a slight increase in compilation time due to the bundler's build pipeline.

Zero-Runtime CSS-in-JS adds processing time for parsing and conversion. However, understanding and acknowledging these factors is often the basis for the concept of Zero-Runtime, which signifies that no runtime remains in the execution environment.

Abstracting Layer concept

Because we had no performance concerns, we were able to dedicate a lot of resources to developing toolchains such as ESLint and Bundler. As a result, the cognitive overhead of style coding is structurally eliminated at the abstraction layer.

Styles written in Plumeria remain as a higher-level abstraction layer and are safely removed from the output by the build plugin (output layer). This is achieved through a design that completely separates the abstraction layer and the output layer. As a result, style definitions do not remain as JavaScript at runtime; only CSS smaller than the definition is output.

Usage

In practice, this means styling becomes straightforward.
You define styles once, and everything else is handled by the compiler.

Use css.create() to define an object as a style. At this point, the atomic hash is determined, and all that remains is to receive it via styleName.

import * as css from "@plumeria/core";

const styles = css.create({
  text: {
    fontSize: 16,
  },
});

export const Footer = () => {
  return <div styleName={styles.text}>MyText</div>;
};

Compile to zero across file boundaries: "@plumeria/core" import is required for compilation.
Styles can be colocated with components or shared across files — structure them to fit your project architecture.

styles.ts

export const styles = css.create({...});

Component.tsx

import "@plumeria/core";
import { styles } from './styles';

styleName={styles.common}

Specificity

styleName prop accepts ternary operators and conditional expressions, and the style properties on the right side always take precedence. For example, if isActive is true, the color of active will override the color of base. The cascade specificity problem is completely resolved by the compiler-controlled merging.