---
title: "tailwindcss-obfuscator"
description: "Open Source CSS Obfuscation Tool for Tailwind CSS v3 & v4"
locale: "en"
canonical: "https://portfolio.josedacosta.info/en/achievements/tailwindcss-obfuscator"
source: "https://portfolio.josedacosta.info/en/achievements/tailwindcss-obfuscator.md"
html_source: "https://portfolio.josedacosta.info/en/achievements/tailwindcss-obfuscator"
author: "José DA COSTA"
date: "2025"
type: "achievement"
slug: "tailwindcss-obfuscator"
tags: ["TypeScript 5.7", "Node.js 18+", "TurboRepo", "pnpm", "tsup", "Vitest", "Babel", "PostCSS", "Commander.js", "VitePress", "magic-string"]
generated_at: "2026-04-23T15:42:48.344Z"
---

# tailwindcss-obfuscator

Open Source CSS Obfuscation Tool for Tailwind CSS v3 & v4

**Date:** Dec 2025 - Jan 2026  
**Duration:** ~6 weeks  
**Role:** Creator & Technical Lead  
**Technologies:** TypeScript 5.7, Node.js 18+, TurboRepo, pnpm, tsup, Vitest, Babel, PostCSS, Commander.js, VitePress, magic-string

## Project Overview

_Protecting CSS intellectual property in the Tailwind ecosystem_

- **Concretely**, the tool kicks in at build time: readable Tailwind classes used in source code (`bg-blue-500 hover:bg-blue-700`) become short, opaque identifiers (`tw-a tw-b`) in the HTML and CSS delivered to the browser. The visual output stays identical, but the design system's textual footprint disappears.
- The tool operates through a **three-phase pipeline**: extraction of Tailwind classes from source files (HTML, JSX, TSX, Vue, Svelte, Astro, Qwik, CSS), deterministic or random mapping generation, and systematic replacement in compiled CSS and templates.
- To break free from this dependency on internals, tailwindcss-obfuscator bets on **static analysis**: rather than patching the Tailwind engine, the tool scans project source files directly to pick up the classes in use. That independence is why it supports both v3 and v4 without friction, whereas the competitor <a href="https://github.com/sonofmagic/tailwindcss-mangle" target="_blank" rel="noopener noreferrer" class="text-primary underline">unplugin-tailwindcss-mangle</a> stayed locked on v3.
- Frontend developers shipping Tailwind CSS to production
- Design agencies protecting their design systems
- SaaS vendors making UI copying harder
- Component library creators selling UI kits

**Tailwind Text:** An **open source npm package** that obfuscates CSS class names generated by Tailwind CSS, transforming readable names like `bg-blue-500` into short opaque identifiers at build time.

**Problem Text:** The only existing competitor relies on patching Tailwind internals - an approach that **broke with Tailwind v4** (Rust/Oxide rewrite). There was no v4-compatible solution on the market.

**Bonus Text:** Beyond intellectual property protection, obfuscation also **significantly reduces HTML weight**. Tailwind's **utility-first** approach causes **heavy repetition of the same class strings** across page markup (e.g. `bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded` duplicated across hundreds of elements). By compacting these classes into short identifiers like `tw-a tw-b`, the tool **reduces the HTML payload size sent to the browser** - a particularly noticeable gain on **long pages**, **SSR streaming** and **mobile payloads**, with a direct impact on **page load time**.

**Feature1 Title:** Static Analysis

**Feature1 Desc:** Framework-agnostic class extraction from HTML, JSX, Vue SFC, Svelte, Astro, Qwik and CSS files

**Feature2 Title:** Dual Parsing

**Feature2 Desc:** Two transformation modes: fast regex for simple cases and precise AST (Abstract Syntax Tree) via Babel + PostCSS for complex scenarios

**Feature3 Title:** Universal Plugins

**Feature3 Desc:** 5 bundler plugins (Vite, Webpack, Rollup, esbuild, Nuxt module) sharing the same core engine

**Feature4 Title:** Tailwind v3 & v4

**Feature4 Desc:** First obfuscation tool compatible with Tailwind v4 (Rust/Oxide engine) - auto-detection of version

## Objectives, Context & Risks

_Strategic positioning in a niche with zero v4-compatible solutions_

**Obj1 Label:** CSS IP Protection

**Obj1 Value:** Opaque class names

**Obj1 Desc:** Prevent trivial copying of design systems from DevTools

**Obj2 Label:** Bundle Size Reduction

**Obj2 Value:** -75% on example

**Obj2 Desc:** 1,247 bytes reduced to 312 bytes on a real-world sample

**Obj3 Label:** Framework Coverage

**Obj3 Value:** 10 frameworks

**Obj3 Desc:** React, Next.js, Vue, Nuxt, SvelteKit, Astro, Remix, Qwik, Solid.js, HTML

**Obj4 Label:** Zero Runtime

**Obj4 Value:** Build-time only

**Obj4 Desc:** No overhead in production - obfuscation happens exclusively at build time

**Context Text:** Tailwind CSS v4, released late 2024, introduced a major breaking change: the engine was rewritten in Rust (**Oxide**) and `tailwind.config.js` gave way to a **CSS-first** configuration sitting directly inside the stylesheets. That rewrite wiped out the only existing obfuscation tool overnight and opened a clear window of opportunity: become the first v4-compatible project.

**Stakes Text:** The tool value is directly proportional to framework coverage - every unsupported framework means lost users. The obfuscation must never break rendering: any undetected class produces a **silent visual bug**, the worst kind of failure in CSS tooling.

**Risk1 Title:** False Negative Extraction

**Risk1 Desc:** When an extractor misses a class present in the compiled CSS, the matching style disappears with no error and no log - the exact scenario raised in the stakes section. Mitigated by 295 tests, 10 test apps, and specialized extractors per framework.

**Risk2 Title:** Tailwind Version Incompatibility

**Risk2 Desc:** Future Tailwind updates could break extraction patterns. Mitigated by auto-detection and modular architecture.

**Risk3 Title:** Dynamic Classes Limitation

**Risk3 Desc:** Classes built at runtime cannot be statically extracted. Documented as an explicit constraint with "static classes only" guidance.

**Risk4 Title:** Third-party Library Conflicts

**Risk4 Desc:** Utility libraries like CVA, clsx, twMerge could break. Mitigated by explicit support for cn(), clsx(), cva(), twMerge(), tv().

## Implementation Phases

_From ecosystem research to npm publication in 6 weeks_

**Phase1 Title:** Research & Analysis

**Phase1 Period:** Dec 7, 2025

**Phase2 Title:** Core Engine

**Phase2 Period:** Dec 7-15, 2025

**Phase3 Title:** Plugins & Integrations

**Phase3 Period:** Dec 8-15, 2025

**Phase4 Title:** Testing & Documentation

**Phase4 Period:** Dec 8-18, 2025

**Phase5 Title:** Publication

**Phase5 Period:** Dec 15, 2025

## Actors & Interactions

_Human + AI collaboration producing 82K lines of code_

### José DA COSTA - Conception & Direction (~25%)

- **Product vision**: identified the market gap for a v4-compatible obfuscator
- **Architecture decisions**: chose TurboRepo monorepo, pnpm workspaces, and static analysis approach
- **Strategic pivots**: abandoned <a href="https://www.npmjs.com/package/tailwindcss-patch" target="_blank" rel="noopener noreferrer" class="text-primary underline">tailwindcss-patch</a> in favor of a custom package
- **Creative direction**: chose colors, logos, sidebar organization, documentation structure
- **Quality control**: verified every page visually, ran manual tests, requested corrections
- **Scope management**: added frameworks progressively (SvelteKit, Astro, Qwik, Solid.js, Remix)

### Claude Code (AI) - Technical Implementation (~75%)

- **Source code**: wrote all 25 TypeScript modules (7,401 lines)
- **Tests**: created all 295 Vitest test cases (4,013 lines)
- **Documentation**: authored all 34 Markdown files (10,404 lines)
- **Test applications**: built and configured 21 apps across 10 frameworks
- **Design**: created SVG logos, VitePress theme (840 lines CSS)
- **Research**: ecosystem analysis, competitor reverse engineering (3,000 lines)

- This project was built as a **Human + AI pair**. José DA COSTA acted as Product Owner, Tech Lead, and QA, while Claude Code (Anthropic AI assistant) handled all code implementation, tests, and documentation.
- The collaboration followed a clear pattern: I formulated needs in natural language, Claude Code executed with technical implementation choices, and I verified visually before requesting adjustments.

**Human Essential Text:** I used AI to accelerate code production, but the project's direction stayed fully human: that is where the product heading, the architecture and the acceptance criteria came from. Without that upstream steering, the agent would have produced technically correct code solving the wrong problem. The list below details what that role covers in practice.

**Ratio Text:** The ~100 prompts produced ~82,000 lines of code and documentation, averaging **~820 lines per prompt**. This ratio illustrates the productivity leverage of AI-assisted development.

**Deps Text:** npm registry (package publication), GitHub (source hosting), Tailwind CSS v3 & v4 (target framework), Babel (JSX/TSX AST - Abstract Syntax Tree - parsing), PostCSS (CSS AST parsing).

## Results & Metrics

_First Tailwind v4 obfuscation tool on the market_

**Metric1 Label:** Source Lines

**Metric1 Value:** 7,401

**Metric1 Desc:** Package TypeScript source code

**Metric2 Label:** Test Cases

**Metric2 Value:** 295

**Metric2 Desc:** In 92 describe blocks

**Metric3 Label:** Documentation

**Metric3 Value:** 10,404

**Metric3 Desc:** Lines of documentation (140% ratio vs code)

**Metric4 Label:** Frameworks

**Metric4 Value:** 10

**Metric4 Desc:** Frontend frameworks supported

**Metric5 Label:** Bundlers

**Metric5 Value:** 4

**Metric5 Desc:** Vite, Webpack, Rollup, esbuild

**Metric6 Label:** Test Apps

**Metric6 Value:** 21

**Metric6 Desc:** Real-world test applications

**For Me Text:** This project deepened my expertise in **AST (Abstract Syntax Tree) manipulation** (Babel parser/traverse, PostCSS selector parsing), **build tool plugin architecture** across 4 bundlers, and the **npm publishing pipeline**. Working with Tailwind v4 Oxide internals provided valuable insight into Rust-based JavaScript tooling. Above all, it validated a Human + AI collaboration pattern I now apply to every project: strong human framing upstream, execution delegated to the agent, then systematic verification of every deliverable.

**For Business Text:** First and only Tailwind v4-compatible obfuscation tool available on npm. Published as open source, impact measurable via npm download counts. Fills a gap left by the v3-only competitor, giving the community a production-ready solution for CSS intellectual property protection.

## What Came After

_From publication to ongoing maintenance_

**Immediate Text:** Published v1.0.0 to npm with professional README, compatibility matrix, and VitePress documentation site. The package was immediately usable via `npm install tailwindcss-obfuscator` with zero-config defaults.

**Medium Text:** The project is in **maintenance mode**, monitoring Tailwind CSS updates for potential breaking changes. The modular architecture (separate extractors, transformers, plugins) makes adding support for new frameworks or bundlers straightforward.

**Current Text:** Published on npm (v1.0.0), source on GitHub. The static analysis approach has proven more resilient than the competitor patch-based approach, validating the initial architectural decision.

## Critical Reflection

_Honest retrospective on decisions and trade-offs_