vue-cssgen
Version:
Инструмент для автоматизации работы со стилями в Vue 3-проектах
268 lines (195 loc) • 10.5 kB
Markdown
# vue-cssgen
[](https://www.npmjs.com/package/vue-cssgen)
[](https://opensource.org/licenses/MIT)
## Описание
**vue-cssgen** — CLI-инструмент для автоматизации и структурирования CSS в проектах на Vue 3.
* Анализирует компоненты, извлекает классы из шаблонов и `<style>`.
* Автоматически генерирует, оптимизирует и выносит CSS в локальные и глобальные файлы по правилам и встречаемости.
* Умеет работать как с автоклассами по правилам (аналог Tailwind), так и с любыми кастомными классами.
* Управляет глобализацией: популярные классы попадают в глобальные стили, редкие остаются локально.
* Сохраняет статистику по классам, помогает находить неиспользуемые стили ("мертвые" классы).
* Позволяет легко расширять и переопределять генерацию под любые требования проекта.
## Возможности
* **Групповой и одиночный запуск:** работает с одной директорией, списком директорий/файлов, либо с отдельным файлом.
* **Статистика классов:** сохраняет подробные json-файлы по автоклассам, пользовательским и неиспользуемым.
* **Гибкая конфигурация:** настраиваемый конфиг, поддержка кастомных правил и исключений.
* **Безопасное обновление стилей:** все глобальные файлы только дополняются, ваши ручные правки не теряются.
* **dryRun-режим:** безопасный анализ без изменений файлов.
* **Поддержка расширения/переопределения любых правил через папку `vue-cssgen-rules`**
* **Автоматический перенос классов между локальными и глобальными файлами в зависимости от количества использований.**
## Быстрый старт
1. **Установка:**
```bash
npm install vue-cssgen --save-dev
# или
yarn add vue-cssgen --dev
```
2. **Создай конфиг:**
`vue-cssgen.conf.js` в корне проекта:
```js
export default {
projectRoot: "./",
componentsDir: ["./src/components", "./src/pages/Home.vue"], // массив путей к папкам или .vue-файлам
resultsDir: "vue-css-stat", // директория для статистики
files: {
statsAuto: "stats-auto.json",
statsCustom: "stats-custom.json",
statsDead: "stats-dead.json",
},
globalCssFile: "./src/assets/css/global.css",
globalCustomCssFile: "./src/assets/css/global-custom.css",
dryRun: false,
logLevel: 'info',
globalThreshold: 2,
extractUserCustom: true
};
```
* `componentsDir` — массив путей к папкам и/или отдельным `.vue`-файлам.
* `globalThreshold` — порог вынесения класса в глобальные стили (>= столько компонентов — глобализация).
3. **Добавь npm-скрипт:**
```json
"scripts": {
"css-gen": "vue-cssgen"
}
```
4. **Запусти:**
```bash
npm run css-gen
# или
npx vue-cssgen
```
5. **Проверь результат:**
* Все локальные и глобальные стили будут актуализированы без потери ручных изменений.
* В каталоге статистики появятся файлы с отчетами по всем классам.
## Расширение и кастомизация
### Пользовательские правила
Создай папку `vue-cssgen-rules` в корне проекта. Добавляй свои правила:
```js
// vue-cssgen-rules/project-rules.js
export default [
{
match: /^bdc-hex_[a-fA-F0-9]{3,6}$/,
css: cls => {
const val = cls.replace('bdc-hex_', '');
return `.${cls} { border-color: #${val} !important; }`;
},
group: 'border',
desc: 'border-color HEX',
modifiable: true,
examples: ['bdc-hex_222', 'bdc-hex_ff0000'],
values: null,
prefix: 'bdc-hex_'
},
];
```
* Файл должен экспортировать массив объектов с ключами: `match` (RegExp), `css` (функция генерации), `group`, `desc` и т.д.
* Все ваши правила объединяются с дефолтными. Совпадающие `match` переопределяют правила из пакета.
### Игнор-листы
Пакет поддерживает white/black/global-игнор-листы в папке `lists/`:
* `whitelist.js`, `blacklist.js`, `globalStyleIgnore.js`
Пример:
```js
// lists/globalStyleIgnore.js
export default function(className) {
return (
/^bg-img_/.test(className) ||
/^private-/.test(className) ||
className.endsWith('-once')
);
};
```
## Ключевые сценарии использования
* **Один файл:**
```bash
npx vue-cssgen src/components/MyBlock.vue
```
* **Несколько директорий или файлов:**
В конфиге передай массив путей:
```js
componentsDir: ["./src/components", "./src/pages", "./src/SomeComponent.vue"]
```
## Как работает обработка
1. Все классы из статических атрибутов `class` в `<template>` парсятся и сравниваются с правилами.
2. Для автоклассов по правилам — генерируется CSS согласно логике пакета/ваших правил.
3. Для пользовательских (непопавших под правила) — сохраняется CSS из `<style>` блока.
4. Популярные классы (кол-во компонентов >= `globalThreshold`) попадают в глобальные стили. Остальные — остаются/переносятся локально.
5. Мёртвые классы из `<style>`, которые не используются в шаблоне, помечаются как `// #мертвый-класс-...`.
6. Все действия фиксируются в статистике (json-файлы в resultsDir).
## Дополнительные команды
* **Генерация справочника классов:**
```bash
npx generate-css
```
Создаёт файл `all-classes.css` со всеми доступными автоклассами.
* **Визуальный UI:**
Открой `ui.html` в корне пакета для просмотра всех автоклассов и описаний.
## Примеры
### Пользовательский конфиг
```js
// vue-cssgen.conf.js
export default {
projectRoot: "./",
componentsDir: ["./src/components"],
resultsDir: "vue-css-stat",
files: {
statsAuto: "stats-auto.json",
statsCustom: "stats-custom.json",
statsDead: "stats-dead.json"
},
globalCssFile: "./src/assets/css/global.css",
globalCustomCssFile: "./src/assets/css/global-custom.css",
dryRun: false,
logLevel: 'info',
globalThreshold: 2,
extractUserCustom: true
};
```
### Пример npm-скрипта
```json
"scripts": {
"css-gen": "vue-cssgen"
}
```
### Пользовательское правило
```js
// vue-cssgen-rules/my-color.js
export default [
{
match: /^c-(red|blue|green)$/,
css: cls => `.${cls} { color: ${cls.slice(2)}; }`,
group: 'color',
desc: 'text color',
examples: ['c-red', 'c-blue']
}
];
```
## FAQ
* **Как сохраняются ручные правки в глобальных CSS?**
Все ваши правки в глобальных файлах сохраняются — скрипт только добавляет новые классы, ничего не перезаписывает.
* **Как добавить или изменить генерацию для класса?**
Просто добавьте или измените правило в `vue-cssgen-rules`.
* **Что такое dryRun?**
Если включить, ни один файл не будет изменён. Только вывод статистики и логов.
* **Мёртвые классы?**
Все классы, которые есть в `<style>`, но не используются в шаблоне, будут помечены комментарием и/или вынесены в отдельную статистику.
* **Как игнорировать динамические классы?**
Динамические классы `:class` не учитываются, только статические string-классы.
## Полезное
* Для крупных проектов сначала используйте dryRun для безопасной проверки.
* Используйте кастомные правила через `vue-cssgen-rules`.
* Настраивайте порог глобализации (globalThreshold) под размер проекта.
* Запускайте инструмент регулярно для поддержания чистоты CSS.
**Автор:** Кузьминский Максим П — [i@m-letto.ru](mailto:i@m-letto.ru)
Лицензия: MIT
Проект [vodorod-ai.ru](https://vodorod-ai.ru)