Skip to content

About

teacss-vs-tailwindcss

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

teacss-vs-tailwindcss

A reproducible performance comparison of three atomic CSS engines on the same machine, the same paired corpus and the same build pipelines (Vite, PostCSS, Rsbuild and Bun): the TeaCSS TypeScript engine (@teacss/core with @teacss/vite-ts), the TeaCSS Rust engine (@teacss/engine with @teacss/vite and the other teacss-rs integrations) and Tailwind CSS v4 (Oxide). Since 0.10 the two TeaCSS engines are separate ecosystems that share no package (ADR-0005).

Status

The subjects now pin TeaCSS 0.10 under spec revision 10: teacss-rs 0.10.5 and teacss-ts 0.10.5, two ecosystems that share no package, on Node 26 (ADR-0005).

Eight published runs; the latest (2026-11-03) is the first of TeaCSS 0.10, across Vite, PostCSS, Rsbuild, Bun and the two CLIs (what changed in 0.10). Its Node binary adds about 70 ms to every Node process, which favours no tool but makes absolute build times high; the audit explains it. The seventh run measured TeaCSS 0.9.3 under spec revision 8. Revisions 5 to 8 made each subject process match what a CLI user gets: the compile cache and the NODE_ENV the vite and rsbuild CLIs set, only the packages the task uses, and a run that is discarded when the machine gets busy mid-run. Build, dev and cold-engine numbers are therefore not comparable with earlier runs. Revision 6 also corrected a bias that made every earlier TypeScript-engine dev number too fast. The CSS of 0.9.3 is byte-for-byte the same as that of 0.9.0 (what changed in 0.9.2 and 0.9.3). Two articles explain the 0.9.0 round in plain language: the TypeScript engine against the Rust engine and TeaCSS against Tailwind CSS v4. Fixes merged but not yet published are measured separately in an unreleased lane that never enters the block below (optimization cards). The block below is generated by bun run bench:report <results.json> --readme README.md after every run and is written for developers who want the answer without reading the full report.

Results from 2026-11-03

Generating the CSS for 20,000 classes (median of 30 runs)

Time
TeaCSS (Rust engine) 42 ms
Tailwind CSS v4 226 ms (5.4× slower)
TeaCSS (TypeScript engine) 466 ms (11.1× slower)

Adding new classes to an engine that already holds those 20,000 (median of 30 runs)

+10 classes +100 classes
TeaCSS (Rust engine) 6.2 ms 7.4 ms
Tailwind CSS v4 116 ms (18.5× slower) 123 ms (16.7× slower)
TeaCSS (TypeScript engine) 116 ms (18.6× slower) 124 ms (16.7× slower)

Saving a new file in the Vite dev server with 20,000 classes already in 300 files, until the page's stylesheet has the new classes (median of 30 runs)

+10 classes +100 classes
TeaCSS (Rust engine) 74 ms 81 ms
TeaCSS (TypeScript engine) 271 ms (3.7× slower) 300 ms (3.7× slower)
Tailwind CSS v4 310 ms (4.2× slower) 322 ms (4.0× slower)

Building a Vite project with those classes in 300 files (median of 30 runs; the project builds in 250 ms with no CSS tool)

Build of which CSS
TeaCSS (Rust engine) 388 ms 139 ms
Tailwind CSS v4 779 ms (2.0× slower) 529 ms
TeaCSS (TypeScript engine) 1.04 s (2.7× slower) 793 ms

What the Rust engine changes for TeaCSS

TypeScript engine Rust engine
Generate the CSS (warm process) 466 ms 42 ms (11.1× faster)
Add 10 classes to a running engine 116 ms 6.2 ms (18.6× faster)
Dev server: save a file with 10 new classes 271 ms 74 ms (3.7× faster)
Vite production build 1.04 s 388 ms (2.7× faster)
Resident memory after generating 699.0 MB 294.3 MB (2.4× less)
Same CSS output byte-identical from the engines and the Vite builds; the dev servers differ in the bundled fonts only, which @teacss/vite inlines and @teacss/vite-ts links

In short

  • TeaCSS (Rust engine) is fastest both at generating the CSS and at finishing the build.
  • For the same classes, Tailwind CSS v4 emits 2.6× the CSS of TeaCSS: 30,010 rules against 4,834. Part of its build time goes to producing that extra output.
  • The price of the Rust engine is a native file of 9.2 MB per platform (8 platform packages), loaded in 2.4 ms. It served 2 of the 2 example configurations it was given.
  • Every tool was given the same classes, and before anything was timed each tool's output was checked against them; every timed call that added classes was checked for those classes. The tools emit different colour and size values by design, so this is the time to a correct stylesheet, not to identical bytes.
  • vite 8.3.4, @teacss/core 0.10.5, @teacss/engine 0.10.5, tailwindcss 4.3.3; one Apple M2 Max, Node v26.12.0. Milliseconds will differ on your machine; the ratios carry over.
  • With each tool's out-of-the-box entry instead of the tuned one, the build takes 0.97× as long for TeaCSS (Rust engine), 1.00× as long for TeaCSS (TypeScript engine) and 1.01× as long for Tailwind CSS v4, so the comparison does not hinge on one tool's configuration.
  • On other build tools: with Rsbuild, TeaCSS (Rust engine) adds 310 ms to the build and Tailwind CSS v4 adds 960 ms, so TeaCSS (Rust engine) adds less; with Bun (Bun runtime), TeaCSS (Rust engine) adds 96 ms to the build and Tailwind CSS v4 adds 320 ms, so TeaCSS (Rust engine) adds less. The Build tools section of the full report sets them beside Vite.

Full report · audit · raw samples · method

Layout

The repository follows Billgo's standard architecture for a Node.js tool: four layers, one dependency direction, one process per native runtime.

Unit Layer Holds
apps/bench shell main.ts (the orchestrator) and subject.ts (one measured subject per process)
packages/benchmark product measure, verify, report, profile and environment features; the shared corpus model and CSS helpers; the composition root; the process contract; persistence
packages/infrastructure foundation config, logging, clock, processes, workspace, the SubjectClient interface and its fakes
packages/subject-* isolation one measured runtime each behind the SubjectClient interface
results/ data raw samples committed with each report
docs/ documentation proposals, specs, plans, ADRs, knowledge, reports, articles

A shell depends on exactly one product. The product depends on the foundation and the isolation units, and only its composition root picks an implementation. An isolation unit depends on the foundation alone. The foundation depends on nothing in the workspace. scripts/check-layout.ts and scripts/check-dependencies.ts fail the build on any deviation.

Develop

Bun installs the workspace; Node 26 runs the TypeScript sources directly, so there is no build step. The teacss-rs packages need Node 26 or later.

bun install
bun run check

bun run check runs Biome, the per-package type checks, the tests and both structure checks. Each script can run on its own: bun run lint:check, bun run typecheck, bun run test, bun run check:layout, bun run check:dependencies.

Measure

bun run bench:verify --utilities 5000 --files 30   # equivalence checks on one corpus
bun run bench:cases                                  # the behaviours the 0.10 upgrade guide names
bun run bench                                        # the full matrix, 30 samples per cell, into results/
bun run bench:ts-tailwind                            # the same without teacss-rs
bun run bench:report results/<file>.json --readme README.md   # report, JSON summary, and the README block

bun run bench measures each tool twice: with the tuned production entry and with the entry its setup guide gives (--group main,default-config, the default). The other groups run on request, all of them at once with --group main,default-config,postcss,rsbuild,bun,cli: the PostCSS integrations (postcss), Rsbuild and Bun (rsbuild, bun), and the two TeaCSS command lines, teacss-cli and teacss (cli). teacss-ts publishes no PostCSS, Rsbuild or Bun integration since 0.10, so those groups have one TeaCSS subject, on the Rust engine.

Verification compares the two TeaCSS engines byte for byte, the two command lines byte for byte with font URLs reduced to their digest, and the two Vite plugins byte for byte. @teacss/vite 0.10.4 let its sheet skip Vite's CSS pipeline, so revision 9 compared the plugins class by class; 0.10.5 fixes it, and revision 10 restores the byte check. Every build is also checked with another stylesheet imported ahead of the tool's own, which @teacss/vite 0.10.3 failed under Vite 8.

To check that the generated corpus is not cherry-picked, run the same matrix on classes taken from real Tailwind projects. List checked-out projects in a JSON file, [{ "name": "…", "dir": "path/to/src" }], then:

bun run bench:corpus --community projects.json     # coverage: how many of their utilities translate
bun run bench --community projects.json --out results
bun run bench:report results/<generated>.json --beside results/<community>.json --readme README.md

The bench GitHub workflow runs the same matrix on a Linux runner and uploads its record as an artifact. Download it and attach it as a cross-check; the report refuses records that ran a different spec revision or corpus:

bun run bench:report results/<local>.json --cross <ci-record>.json --readme README.md

To measure unreleased TeaCSS builds, link a built teacss-ts checkout (@teacss/core, @teacss/vite-ts, @teacss/preset-standard), or a built teacss-rs engine (npm run build && npm run build:ts in its packages/engine) under the published TeaCSS packages. One link at a time:

bun run bench:link link --ts ../teacss-ts   # bench:link status shows where each package resolves
bun run bench:link link --rs ../teacss-rs   # every @teacss/engine the subjects reach, published packages otherwise
bun run bench:link unlink

A report from a linked run says so on its first line and is not for publication. bun run bench refuses to start when the one-minute load exceeds 20 % of the logical cores; --allow-busy records the run anyway and the report says so. node apps/bench/src/main.ts --help lists every option. Bun is the package manager; Node 26 runs the harness and every measured process, because that is the runtime a Vite build uses by default (ADR-0003).

About

teacss-vs-tailwindcss

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages