Maxim Tsatsura 

Новый инструмент: tailwind-prefix-migrator — как изолировать Tailwind и shadcn в виджетах без регексов и боли

Всем привет! Продолжаю делиться своими open-source инструментами, которые родились из реальных производственных задач.

Когда вы делаете встраиваемый виджет, личный кабинет, калькулятор или микрофронтенд на стеке React + Tailwind CSS + shadcn/ui, всё работает прекрасно — ровно до того момента, пока вам не нужно встроить его скриптом на рабочий сайт клиента (например, на WordPress, Bitrix или самописную CMS).

И тут начинается хаос со стилями:

1. Чужие глобальные стили ломают ваш виджет (например, базовые правила для div, p или button).

2. Ваши классы вроде `flex`, `p-4`, `bg-white` или стили сброса (preflight) ломают вёрстку сайта клиента.

Обычно разработчики пробуют три пути, и у всех есть фатальные минусы:

→ iframe: тяжело масштабировать под контент, неудобный скролл, на мобильных устройствах страдает UX, а модальные окна зажаты рамками фрейма.

→ Shadow DOM: моментально ломает портальные компоненты (модалки Radix/shadcn, тултипы, селекты и дропдауны рендерятся в <body> за пределами Shadow Root).

→ Автозамена классов регулярками / find-and-replace: лотерея, которая почти всегда ломает кастомные BEM-классы, иконки Lucide (`lucide-`), ключи вариантов в CVA (`cva()`) или переменные в JavaScript.

Поэтому я написал и опубликовал tailwind-prefix-migrator (CLI-команда `tpm`).

Это инструмент, который безопасно расставляет, обновляет или полностью снимает префиксы Tailwind по всей кодовой базе за пару секунд.

Главное отличие — он не гадает по регулярным выражениям. Он строит настоящее абстрактное синтаксическое дерево (AST):

• Код JS/TS/TSX разбирается через @babel/parser и @babel/traverse.

• Стили CSS/SCSS разбираются через PostCSS.

Что умеет под капотом:

• Понимает структуру shadcn/ui и CVA: префиксит только сами классы, оставляя в покое ключи вариантов (например, `variant: { default: ... }`).

• Заглядывает внутрь хелперов: автоматически обходит аргументы функций `cn()`, `clsx()`, `twMerge()`, `classNames()`.

• Изолирует CSS-переменные темы: превращает `--primary` в `--calc-primary`, а `var(--primary)` в `var(--calc-primary)`.

• Оборачивает стили в @layer: автоматически заворачивает `@tailwind` директивы в изолированный `@layer <имя>`, исключая конфликты с хост-сайтом.

• Базируется на словарях утилит: знает полные словари классов Tailwind v3 и v4, поэтому не трогает чужие классы, названия библиотек и сторонние стили.

• Синхронизирует конфиги: сам обновляет параметр `prefix` и отключает `preflight` в `tailwind.config.*` и `components.json`.

• Мгновенный откат одной командой: `tpm revert` аккуратно снимает префиксы и возвращает исходное состояние кодовой базы.

• Безопасен для Git: файлы, где ничего не менялось, не перезаписываются и не засоряют историю коммитов.

Инструмент не требует обязательной установки в зависимости, его можно запустить на лету через npx:

npx tailwind-prefix-migrator init

npx tailwind-prefix-migrator apply --dry-run

npx tailwind-prefix-migrator apply

Полезные ссылки:

• NPM: https://www.npmjs.com/package/tailwind-prefix-migrator

• GitHub: https://github.com/Maks-T/tailwind-prefix-migrator

Если вы разрабатываете виджеты, калькуляторы или изолированные дизайн-системы — буду рад, если инструмент сбережёт вам кучу времени и нервов.

Любой фидбек, багрепорты и звёздочки на GitHub очень приветствуются. Спасибо всем, кто поддерживает меня здесь на Boosty — благодаря вам появляется время упаковывать такие внутренние утилиты в качественный Open Source!