PathLogs UI
English

Начало

CLI и реестр

Как виджеты попадают в проект и почему они копируются, а не ставятся.

Тяжёлые виджеты не ставятся пакетом — они копируются в код проекта одной командой и дальше живут как обычные ваши файлы.

Почему копированием

Доска и диаграмма почти всегда требуют правок под конкретный домен: другое тело карточки, другие права, другой набор действий. Компонент, который нельзя открыть и поправить, обрастает пропсами — renderCardHeader, hideAssignees, cardClassName — и через полгода его API больше него самого.

init

terminal
npx @toimetdev/pathlogs-ui init

Команда создаёт настройки, каталог для виджетов и дописывает импорты стилей:

terminal
Настройка PathLogs UI

  каталог виджетов  src/components/ui
  алиас импорта     @/components/ui
  файл стилей       src/app/globals.css
  Tailwind          да

  + pathlogs.json
  + src/components/ui/
  ~ src/app/globals.css (добавлены импорты стилей)

Импорты вставляются после @import "tailwindcss", если он есть: порядок в CSS значим. Повторный запуск ничего не дублирует. Если файла стилей нет, команда не выдумывает чужую структуру, а просто показывает, что вставить.

add

terminal
npx @toimetdev/pathlogs-ui add kanban
npx @toimetdev/pathlogs-ui add gantt filter-bar
npx @toimetdev/pathlogs-ui add kanban --dry-run

Файлы копируются в каталог из настроек, а импорты между ними переписываются под ваш алиас:

tsx
// в реестре
import { columnItems } from "./kanbanOrder";

// у вас в проекте
import { columnItems } from "@/components/ui/kanban/kanbanOrder";

В конце команда печатает, какие пакеты нужны виджету — их список зашит в его метаданных, а не угадывается.

list

terminal
npx @toimetdev/pathlogs-ui list

Показывает, что вообще есть в реестре, с описанием каждого виджета.

pathlogs.json

pathlogs.json
{
  "componentsDir": "src/components/ui",
  "alias": "@/components/ui",
  "css": "src/app/globals.css",
  "tailwind": true
}
componentsDirstring

по умолчанию: "src/components/ui"

Куда класть виджеты, относительно корня проекта.

aliasstring

по умолчанию: "@/components/ui"

Алиас, которым виджеты импортируют друг друга. Пустая строка — оставить относительные пути.

cssstring

по умолчанию: "src/app/globals.css"

Файл, в который init дописывает импорты стилей.

tailwindboolean

по умолчанию: true

Есть ли в проекте Tailwind. Если нет, add предупредит, что виджеты приедут без стилей.

Значения можно задать сразу при настройке: init --dir src/ui --alias @/ui --no-tailwind.

Обновление

Обновлений «на месте» у виджетов нет, и это осознанно: файл в вашем проекте уже может отличаться от исходного, а автоматическое слияние чужих правок — источник тихих поломок.

Если хочется подтянуть свежую версию:

terminal
# посмотреть, что изменится
npx @toimetdev/pathlogs-ui add kanban --dry-run

# перезаписать и разобрать конфликты в git
npx @toimetdev/pathlogs-ui add kanban --force
git diff

Поэтому виджеты стоит коммитить сразу после копирования — тогда git diff покажет ровно ваши правки поверх исходника.

Свой виджет

Реестр — это каталог с файлами и описанием. Добавить свой:

registry/widgets/my-widget/meta.json
{
  "name": "my-widget",
  "title": "Мой виджет",
  "description": "Что делает и чем полезен",
  "type": "widget",
  "dependencies": ["@xyflow/react"],
  "registryDependencies": ["filter-bar"],
  "packageDependencies": ["@toimetdev/pathlogs-core"],
  "tailwind": true,
  "files": [
    { "path": "MyWidget.tsx", "target": "my-widget/MyWidget.tsx" }
  ]
}
  • dependencies — сторонние npm-пакеты;
  • registryDependencies — другие виджеты реестра, они установятся первыми;
  • packageDependencies — пакеты самого фреймворка.

CLI раскрывает зависимости в порядке установки и печатает единую команду npm install для всего, чего не хватает.