ironframe 1.0.0

Production-ready Tailwind CSS v4.1-compatible Rust engine for Node.js/npm-free workflows, including htmx-style web development.
Documentation

ironframe

ironframe is a production-ready Rust implementation targeting high compatibility with Tailwind CSS v4.1 behavior and output. It is designed for teams that want a Tailwind-compatible workflow without installing Tailwind CSS through Node.js or npm. It is especially suited to developers building web apps in ecosystems like htmx, where avoiding Node.js-based tooling is a key requirement. Developed by Finite Field, K.K..

Goals

  • Provide a production-operable Rust CSS engine with Tailwind CSS v4.1-equivalent features
  • Maintain high compatibility with Tailwind CSS utility generation, variants, and directives
  • Deliver reproducible builds, strong performance, and practical developer ergonomics

Target Feature Scope (Tailwind CSS v4.1 Equivalent)

  • Utility class generation
  • JIT compilation
  • Content scanning (HTML/TSX/Vue/etc.)
  • Configuration files (theme, extensions, plugins)
  • Arbitrary values (custom colors/sizes)
  • Layering (base/components/utilities)
  • Variants (hover, focus, dark, etc.)
  • Plugin API
  • Preflight-equivalent reset
  • CLI and build pipeline integration

Approach

  1. Break down features and define requirements
  2. Implement core pieces in Rust (parser, scanner, generator)
  3. Design and operate a production-grade CLI
  4. Benchmark and optimize

Expected Outputs

  • Design documents
  • Rust implementations of core components
  • Minimal CLI
  • Sample projects

Crate Layout

  • src/core.rs: tokenization, AST, and core analysis utilities
  • src/scanner.rs: content scanning and class extraction
  • src/generator.rs: utility class generation and CSS output
  • src/config.rs: configuration, theme, and plugin loading
  • src/lib.rs: CLI orchestration and build pipeline integration
  • src/main.rs: binary entrypoint (ironframe)

CLI Usage

Run

  • Run without installing:
    • cargo run -- <command> [options]
  • Install to your Cargo bin directory:
    • cargo install --path .
    • ironframe --help
  • Build release binary:
    • cargo build --release
    • ./target/release/ironframe --help

Commands

ironframe scan [--ignore <glob>] <glob...>
ironframe build [--output <path>] [--minify] [--input-css <path>] [--compare-css <path>] [--config <path>] [--ignore <glob>] <glob...>
ironframe watch [--output <path>] [--minify] [--input-css <path>] [--config <path>] [--ignore <glob>] [--poll] [--poll-interval <ms>] <glob...>
  • scan
    • scans files and prints unique class candidates to stdout
  • build
    • generates CSS once
    • writes to stdout by default, or to --output <path> (alias: --out, -o) when specified
    • --input-css <path> (aliases: -i, -s) enables processing for @import, @source, @theme, and @apply
    • --compare-css <path> compares generated CSS with a reference CSS and fails if line 2 onward differs (line 1 header is ignored)
    • --config <path> loads TOML config (default: built-in config)
    • --ignore <glob> can be passed multiple times
    • --minify emits minified output
  • watch
    • runs an initial build, then rebuilds on file changes
    • supports the same options as build
    • --poll enables polling mode (useful where filesystem notifications are unreliable)
    • --poll-interval <ms> sets polling interval (default: 500)

Examples

# Scan class candidates
ironframe scan "src/**/*.{html,tsx}"

# Build once to a file
ironframe build --output dist/tailwind.css "src/**/*.{html,tsx}"

# Build with template CSS and config
ironframe build -i src/app.css -c ironframe.toml -o dist/app.css "src/**/*.{html,tsx}"

# Build and compare with Tailwind output (line 1 is ignored)
ironframe build -i src/app.css -o dist/app.css --compare-css dist/app.tailwind.css "src/**/*.{html,tsx}"

# Watch mode (native watcher)
ironframe watch --output dist/tailwind.css "src/**/*.{html,tsx}"

# Watch mode with polling
ironframe watch --poll --poll-interval 250 "src/**/*.{html,tsx}"

When using build --input-css, the CSS file must include @import "tailwindcss" or @import "ironframe" (including split imports such as tailwindcss/theme.css).

Performance Benchmarking

Reusable benchmark scripts are available under bench/.

# Generate benchmark cases
./bench/generate_perf_cases.sh

# Run benchmark suite and save TSV/Markdown results
./bench/run_perf_benchmarks.sh

Outputs:

  • bench/results/latest.tsv
  • bench/results/latest.md
  • versioned snapshots bench/results/perf_*.tsv, bench/results/perf_*.md

Minimal API (Draft)

  • ironframe::core
    • Token and TokenKind for lexer output
    • AstNode for parsed structures
    • ParseError and Diagnostic
    • parse(input: &str) -> Result<AstNode, ParseError>
  • ironframe::scanner
    • ScanTarget and ScanResult
    • ScanGlobOptions
    • scan(paths: &[PathBuf]) -> Result<ScanResult, ScanError>
    • scan_globs(patterns: &[String]) -> Result<ScanResult, ScanError>
    • scan_globs_with_ignore(patterns: &[String], ignore: &[String]) -> Result<ScanResult, ScanError>
    • scan_globs_with_options(patterns: &[String], ignore: &[String], options: &ScanGlobOptions) -> Result<ScanResult, ScanError>
    • extract_classes(text: &str) -> Vec<String>
  • ironframe::generator
    • GeneratorConfig and GenerationResult
    • generate(classes: &[String], config: &GeneratorConfig) -> GenerationResult
    • emit_css(result: &GenerationResult) -> String
  • ironframe::config
    • Config and Theme
    • load(path: &Path) -> Result<Config, ConfigError>
    • resolve_theme(config: &Config) -> Theme
  • ironframe (library crate)
    • binary command: ironframe
    • main with subcommands: scan, build, watch
    • build wires: config -> scanner -> generator -> css

Notes

This repository references Tailwind CSS v4.1 for behavior and ideas but is not affiliated with the official implementation. ironframe is intended for production use and prioritizes high output compatibility with Tailwind CSS while keeping a Rust-only toolchain option.

ironframe build --input-css supports Tailwind-style @source directives for:

  • explicit source registration (@source "../path")
  • source exclusion (@source not "../path")
  • disabling auto detection (@import "tailwindcss" source(none))
  • base path override (@import "tailwindcss" source("../src"))
  • inline safelist / blocklist via brace expansion (@source inline(...), @source not inline(...))

ironframe build --input-css also supports:

  • local CSS import inlining (@import "./tokens.css";)
  • utility inlining with @apply for known utilities (@apply rounded-b-lg shadow-md;)
  • Tailwind-style framework import splitting:
    • @import "tailwindcss"; injects theme + preflight + utilities
    • @import "tailwindcss/theme.css";, @import "tailwindcss/preflight.css";, @import "tailwindcss/utilities.css"; can be imported individually
    • omitting preflight.css disables preflight injection
  • build-time functions in CSS:
    • --alpha(var(--color-lime-300) / 50%) -> color-mix(in oklab, var(--color-lime-300) 50%, transparent)
    • --spacing(4) -> calc(var(--spacing) * 4)

Example Config

ironframe.toml:

[theme]
name = "default"

[theme.colors.gray]
100 = "#f3f4f6"
500 = "#6b7280"

Version History

  • v1.0.0: Speed optimization release focused on faster scanning and CSS generation workflows.

License

MIT OR Apache-2.0