---
title: "tailwindcss-obfuscator"
description: "Outil Open Source d'obfuscation CSS pour Tailwind CSS v3 & v4"
locale: "fr"
canonical: "https://portfolio.josedacosta.info/fr/realisations/tailwindcss-obfuscator"
source: "https://portfolio.josedacosta.info/fr/realisations/tailwindcss-obfuscator.md"
html_source: "https://portfolio.josedacosta.info/fr/realisations/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:41:28.329Z"
---

# tailwindcss-obfuscator

Outil Open Source d'obfuscation CSS pour Tailwind CSS v3 & v4

**Date:** Déc 2025 - Jan 2026  
**Duration:** ~6 semaines  
**Role:** Créateur & Lead Technique  
**Technologies:** TypeScript 5.7, Node.js 18+, TurboRepo, pnpm, tsup, Vitest, Babel, PostCSS, Commander.js, VitePress, magic-string

## Présentation du projet

_Protéger la propriété intellectuelle CSS dans l'écosystème Tailwind_

- **Concrètement**, l'outil intervient au moment du build : les classes Tailwind lisibles utilisées dans le code source (`bg-blue-500 hover:bg-blue-700`) deviennent des identifiants courts et opaques (`tw-a tw-b`) dans le HTML et le CSS livrés au navigateur. Le résultat visuel reste identique, mais l'empreinte textuelle du design system disparaît.
- L'outil fonctionne via un **pipeline en trois phases** : extraction des classes Tailwind depuis les fichiers source (HTML, JSX, TSX, Vue, Svelte, Astro, Qwik, CSS), génération de mapping déterministe ou aléatoire, et remplacement systématique dans le CSS compilé et les templates.
- Pour s'affranchir de cette dépendance aux internals, tailwindcss-obfuscator mise sur l'**analyse statique** : plutôt que de patcher le moteur Tailwind, l'outil scanne directement les fichiers source du projet pour y repérer les classes utilisées. Cette indépendance explique pourquoi il supporte sans rupture les versions v3 et v4, là où le concurrent <a href="https://github.com/sonofmagic/tailwindcss-mangle" target="_blank" rel="noopener noreferrer" class="text-primary underline">unplugin-tailwindcss-mangle</a> est resté bloqué en v3.
- Développeurs frontend déployant Tailwind CSS en production
- Agences de design protégeant leur design system
- Éditeurs SaaS voulant compliquer la copie de leur interface
- Créateurs de bibliothèques de composants commercialisant des UI kits

**Tailwind Text:** Un **package npm open source** qui obfusque les noms de classes CSS générés par Tailwind CSS, transformant les noms lisibles comme `bg-blue-500` en identifiants courts et opaques au moment du build.

**Problem Text:** Le seul concurrent existant repose sur le patching des internals de Tailwind - une approche qui **ne fonctionne plus avec Tailwind v4** (réécrit en Rust/Oxide). Aucune solution compatible v4 n'existait sur le marché.

**Bonus Text:** Au-delà de la protection intellectuelle, l'obfuscation **allège significativement le poids du HTML**. L'approche **utility-first** de Tailwind génère une **forte répétition des mêmes chaînes de classes** dans le corps des pages (ex : `bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded` dupliqué sur des centaines d'éléments). En compactant ces classes en identifiants courts comme `tw-a tw-b`, l'outil **réduit la taille du HTML transféré au navigateur** - un gain particulièrement sensible sur les **pages longues**, le **streaming SSR** et les **payloads mobile**, avec un impact direct sur le **temps de chargement**.

**Feature1 Title:** Analyse statique

**Feature1 Desc:** Extraction de classes agnostique au framework depuis HTML, JSX, Vue SFC, Svelte, Astro, Qwik et CSS

**Feature2 Title:** Double parsing

**Feature2 Desc:** Deux modes de transformation : regex rapide pour les cas simples et AST (Abstract Syntax Tree) précis via Babel + PostCSS pour les scénarios complexes

**Feature3 Title:** Plugins universels

**Feature3 Desc:** 5 plugins bundler (Vite, Webpack, Rollup, esbuild, module Nuxt) partageant le même moteur central

**Feature4 Title:** Tailwind v3 & v4

**Feature4 Desc:** Premier outil d'obfuscation compatible avec Tailwind v4 (moteur Rust/Oxide) - détection automatique de version

## Objectifs, Contexte & Risques

_Positionnement stratégique dans une niche sans solution compatible v4_

**Obj1 Label:** Protection IP CSS

**Obj1 Value:** Noms opaques

**Obj1 Desc:** Empêcher la copie triviale des design systems depuis les DevTools

**Obj2 Label:** Réduction du bundle

**Obj2 Value:** -75% sur exemple

**Obj2 Desc:** 1 247 octets réduits à 312 octets sur un échantillon réel

**Obj3 Label:** Couverture frameworks

**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:** Aucun overhead en production - l'obfuscation s'effectue exclusivement au build

**Context Text:** Tailwind CSS v4, sorti fin 2024, a introduit une rupture majeure : le moteur a été réécrit en Rust (**Oxide**) et `tailwind.config.js` laisse la place à une configuration **CSS-first** directement dans les feuilles de style. Cette réécriture a effacé du jour au lendemain le seul outil d'obfuscation disponible sur le marché, et ouvert une fenêtre d'opportunité nette : devenir le premier projet compatible v4.

**Stakes Text:** La valeur de l'outil est directement proportionnelle au nombre de frameworks supportés - chaque framework non supporté est un utilisateur perdu. L'obfuscation ne doit jamais casser le rendu : toute classe non détectée produit un **bug visuel silencieux**, le pire type de défaillance en outillage CSS.

**Risk1 Title:** Faux négatif d'extraction

**Risk1 Desc:** Lorsqu'un extracteur laisse échapper une classe présente dans le CSS, le style correspondant disparaît sans erreur ni log : c'est précisément le scénario évoqué dans les enjeux. Atténuation par **295 tests**, **10 apps de test** et **extracteurs spécialisés par framework**.

**Risk2 Title:** Incompatibilité version Tailwind

**Risk2 Desc:** Les **futures mises à jour Tailwind** pourraient casser les patterns d'extraction. Atténuation par **auto-détection** et **architecture modulaire**.

**Risk3 Title:** Limitation classes dynamiques

**Risk3 Desc:** Les **classes construites au runtime** ne peuvent pas être extraites statiquement. Documenté comme contrainte explicite avec guidance "static classes only".

**Risk4 Title:** Conflits bibliothèques tierces

**Risk4 Desc:** Les utilitaires comme **CVA**, **clsx**, **twMerge** pourraient causer des problèmes. Atténuation par support explicite de `cn()`, `clsx()`, `cva()`, `twMerge()`, `tv()`.

## Phases de réalisation

_De la recherche écosystème à la publication npm en 6 semaines_

**Phase1 Title:** Recherche & Analyse

**Phase1 Period:** 7 déc 2025

**Phase2 Title:** Moteur central

**Phase2 Period:** 7-15 déc 2025

**Phase3 Title:** Plugins & Intégrations

**Phase3 Period:** 8-15 déc 2025

**Phase4 Title:** Tests & Documentation

**Phase4 Period:** 8-18 déc 2025

**Phase5 Title:** Publication

**Phase5 Period:** 15 déc 2025

## Acteurs & Interactions

_Collaboration Humain + IA produisant 82K lignes de code_

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

- **Vision produit** : identification du manque sur le marché pour un obfuscateur compatible v4
- **Décisions d'architecture** : choix du monorepo TurboRepo, pnpm workspaces et approche par analyse statique
- **Pivots stratégiques** : abandon de <a href="https://www.npmjs.com/package/tailwindcss-patch" target="_blank" rel="noopener noreferrer" class="text-primary underline">tailwindcss-patch</a> au profit d'un package custom
- **Prompt engineering** : rédaction des instructions détaillées transmises à l'IA, découpage des tâches en étapes vérifiables, cadrage du périmètre à chaque itération
- **Directives de style** : définition des conventions de code (TypeScript strict, nommage, organisation des modules), charte éditoriale de la documentation, choix des couleurs et logos
- **Revue de code** : relecture systématique de chaque module produit par l'IA, validation des choix d'implémentation, refactorisation manuelle quand nécessaire
- **Vérification de conformité** : contrôle de cohérence entre le code, les tests et la documentation, validation de l'alignement avec les spécifications Tailwind v3/v4
- **Systèmes de contrôle qualité** : mise en place de la configuration Vitest, ESLint, TypeScript strict, règles d'interdiction TODO/FIXME, seuils de couverture de tests
- **Contrôle qualité visuel** : vérification visuelle de chaque page de documentation, tests manuels bout en bout sur les 21 apps de test, demandes de corrections ciblées
- **Gestion du périmètre** : ajout progressif de frameworks (SvelteKit, Astro, Qwik, Solid.js, Remix), arbitrage des compromis scope/qualité/délai
- **Validation des livrables** : tests d'intégration manuels, vérification des exports ESM/CJS/DTS, validation du README et de la matrice de compatibilité avant publication npm

### Claude Code (IA) - Implémentation technique (~75%)

- **Code source** : écriture de l'intégralité des 25 modules TypeScript (7 401 lignes) - extracteurs, transformers, plugins, CLI, API publique
- **Tests unitaires** : création de l'ensemble des 295 cas de test Vitest (4 013 lignes), couverture exhaustive des extracteurs, transformers et cas limites
- **Documentation** : rédaction des 34 fichiers Markdown (10 404 lignes) - guides, référence API, matrices de compatibilité, exemples par framework
- **Applications de test** : construction et configuration de 21 apps réelles sur 10 frameworks (React, Vue, Nuxt, SvelteKit, Astro, Qwik, Remix, Solid.js, Next.js, HTML)
- **Design** : création des logos SVG clair/sombre, personnalisation du thème VitePress (840 lignes CSS custom), icônes et assets de marque
- **Recherche & analyse** : étude de la documentation Tailwind v3/v4, reverse engineering des concurrents, catalogue des 100+ variants à supporter (3 000 lignes)
- **Outillage de build** : configuration tsup pour exports ESM + CJS + DTS, setup TurboRepo et pnpm workspaces, scripts de publication npm
- **Itérations correctives** : application des retours de revue, correction des faux négatifs d'extraction, ajustements fins des patterns regex et AST

- Ce projet a été réalisé en **binôme Humain + IA**. José DA COSTA a joué le rôle de Product Owner, Tech Lead et QA, tandis que Claude Code (assistant IA Anthropic) a pris en charge toute l'implémentation du code, des tests et de la documentation.
- La collaboration a suivi un schéma clair : je formulais mes besoins en langage naturel, Claude Code exécutait avec des choix d'implémentation techniques, et je vérifiais visuellement avant de demander des ajustements.

**Human Essential Text:** J'ai utilisé l'IA pour accélérer la production de code, mais la direction du projet est restée entièrement humaine : c'est de là que venaient le cap produit, l'architecture et les critères d'acceptation. Sans ce pilotage en amont, l'agent aurait produit du code techniquement correct mais résolvant le mauvais problème. La liste ci-dessous détaille concrètement ce que ce rôle recouvre au quotidien.

**Ratio Text:** Les ~100 prompts ont produit ~82 000 lignes de code et documentation, soit en moyenne **~820 lignes par prompt**. Ce ratio illustre l'effet de levier de l'IA sur la productivité.

**Deps Text:** Registre npm (publication), GitHub (hébergement du code), Tailwind CSS v3 & v4 (framework cible), Babel (parsing AST - Abstract Syntax Tree - JSX/TSX), PostCSS (parsing AST CSS).

## Résultats & Métriques

_Premier outil d'obfuscation Tailwind v4 sur le marché_

**Metric1 Label:** Lignes source

**Metric1 Value:** 7 401

**Metric1 Desc:** Code source TypeScript du package

**Metric2 Label:** Cas de test

**Metric2 Value:** 295

**Metric2 Desc:** Dans 92 blocs describe

**Metric3 Label:** Documentation

**Metric3 Value:** 10 404

**Metric3 Desc:** Lignes de documentation (ratio 140% vs code)

**Metric4 Label:** Frameworks

**Metric4 Value:** 10

**Metric4 Desc:** Frameworks frontend supportés

**Metric5 Label:** Bundlers

**Metric5 Value:** 4

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

**Metric6 Label:** Apps de test

**Metric6 Value:** 21

**Metric6 Desc:** Applications de test réelles

**For Me Text:** Ce projet a approfondi mon expertise en **manipulation d'AST (Abstract Syntax Tree)** (Babel parser/traverse, PostCSS selector parsing), en **architecture de plugins** pour 4 bundlers, et dans le **pipeline de publication npm**. Travailler avec les internals Tailwind v4 Oxide m'a apporté une compréhension précieuse de l'outillage JavaScript basé sur Rust. Surtout, il a validé un pattern de collaboration Humain + IA que j'applique désormais à tous mes projets : cadrage humain fort en amont, exécution déléguée à l'agent, puis vérification systématique des livrables.

**For Business Text:** Premier et seul outil d'obfuscation Tailwind compatible v4 disponible sur npm. Publié en open source, impact mesurable via les compteurs de téléchargement npm. Comble le vide laissé par le concurrent bloqué sur v3, offrant à la communauté une solution prête pour la production en matière de protection de propriété intellectuelle CSS.

## Les lendemains du projet

_De la publication à la maintenance continue_

**Immediate Text:** Publication de la **v1.0.0 sur npm** avec **README professionnel**, **matrice de compatibilité** et **site de documentation VitePress**. Le package était immédiatement utilisable via `npm install tailwindcss-obfuscator` avec des **paramètres par défaut sans configuration**.

**Medium Text:** Le projet est en **mode maintenance**, **surveillant les mises à jour de Tailwind CSS** pour d'**éventuelles ruptures de compatibilité**. L'**architecture modulaire** (extracteurs, transformers et plugins séparés) facilite l'**ajout de support** pour de nouveaux frameworks ou bundlers.

**Current Text:** Publié sur npm (v1.0.0), source sur GitHub. L'approche par analyse statique s'est avérée plus résiliente que l'approche par patch du concurrent, validant la décision architecturale initiale.

## Regard critique

_Rétrospective honnête sur les décisions et compromis_