Интеграция

#Зачем нужна Git-интеграция

Git-интеграция превращает SXL Studio в двусторонний мост между Figma и репозиторием кода. Дизайнеры обновляют токены в плагине → Push → разработчики получают изменения. Разработчики обновляют JSON → дизайнер делает Pull → макеты обновляются автоматически.

Что синхронизируется

В Dev Mode также может использоваться Code folder для .vue-редактора репозитория. Эта папка с исходниками отделена от синхронизации данных и токенов.

Поддерживаемые провайдеры

• GitHub — github.com и GitHub Enterprise Server (GHES)
• GitLab — gitlab.com и self-hosted инстансы

Git-интеграция работает через REST API провайдера (не через git CLI). Подключение происходит по Personal Access Token.

#Рекомендуемый порядок (с нуля)

1. Установите и запустите Bridge версии @sxl-studio/bridge ≥ 1.7.0 на своём компьютере — см. Утилита Bridge. Проверка: в терминале выполните curl http://127.0.0.1:37830/api/status — должен вернуться JSON с полем ports (если использовали другой порт — подставьте его в URL).
2. Создайте Personal Access Token у провайдера с нужными правами на репозиторий — пошагово: GitHub, GitLab.
3. В Figma откройте плагин SXL Studio → панель Sync → New Sync. Заполните репозиторий, ветку, Data Path и Tokens Path, вставьте токен доступа. Если нужно обойти лимит Figma clientStorage (~5 MB), включите Local Storage (Bridge должен быть запущен) → Save.
4. Нажмите Pull и дождитесь завершения. Дальше работайте с Push, ветками и индикаторами по разделам ниже.

Git Sync работает и без Bridge; Local Storage нужен, когда объём токенов и данных приближается к лимиту хранилища плагина в Figma.

#Local Mode, Git Sync и Local Storage

Это разные вещи:

• Local Mode — выбран в Sync Mode, когда активного Git-подключения нет. Вы работаете только с локальными данными плагина в этом файле Figma.
• Git Sync режим — выбрано активное подключение GitHub/GitLab. Доступны Pull/Push, работа с ветками и Git-статус.
• Local Storage — переключатель в конкретном подключении, который выносит тяжёлые данные на диск через Bridge, чтобы не упираться в лимит Figma clientStorage.

Для средних и больших проектов рекомендуется включать Local Storage. Это снижает риск переполнения квоты, повышает стабильность на больших объёмах токенов/данных и помогает избежать потери синхронизируемых данных из-за ограничений хранилища.

#Настройка подключения

Шаг 1 — Создайте подключение

1. Откройте панель Sync в плагине (иконка в нижней панели)
2. Нажмите New Sync
3. Заполните поля:

4. Нажмите Save

Старые сохранённые подключения автоматически мигрируют с legacy-имён полей на текущие Access Token / Repository. Если после миграции подключение выглядит неполным, откройте его, проверьте поля и сохраните заново.

В Figma Dev Mode форма подключения фокусируется на Code folder. Code-only подключение подходит для вкладки Dev Code, но Pull/Status может вернуть "nothing to pull", потому что Database и Tokens управляются из Design Mode sync settings.

Шаг 2 — Первый Pull

После создания подключения выполните Pull — плагин загрузит все файлы из указанных папок в репозитории.

Миграция из Tokens Studio

Если репозиторий был экспортирован из Tokens Studio, запустите Migration TS после первого Pull и до первого SXL export.

Кнопка находится в Git Sync, рядом с New Sync, когда выбрано активное подключение. Она показывает preview конвертации JSON из Tokens Studio в SXL DTCG, маппит типы Tokens Studio в типы SXL и может преобразовать $themes.json в SXL config.json.

Миграция не делает Push автоматически и не мутирует Figma Variables или Styles. После применения проверьте Push diff. Перед export в существующую Figma-библиотеку используйте Bind existing by name или ваш rebind/adoption-процесс, если подходящие Variables/Styles уже существуют.

Подробнее: Миграция из Tokens Studio.

#Push — отправка изменений

Что происходит при Push

1. Плагин собирает все локальные изменения:
   • Данные (датасеты, маппинги, изображения)
   • Токены (JSON-файлы, config.json, diff-id, code-connect.json, diff-grid.*)
2. Сравнивает с состоянием на remote (по SHA)
3. Формирует один коммит с изменениями
4. Отправляет на выбранную ветку

Как сделать Push

1. Нажмите кнопку Push в нижней панели (или через меню Git)
2. Откроется Commit Modal с встроенным inline side-by-side diff:
   • Слева — список изменённых файлов с иконками статуса (+ / ~ / ×) и счётчиком
   • Справа — Monaco DiffEditor: Remote слева, Local справа. Кликайте файлы в списке, чтобы переключать сравнение. Бинарные ассеты в списке отмечены отдельно и diff для них не строится
   • Навигация по изменениям: F7 — следующий hunk, Shift+F7 — предыдущий (либо стрелки ↑ / ↓ в правом верхнем углу редактора)
   • Ниже — поле commit message с подсказкой о ветке и провайдере
3. Введите описание коммита
4. Нажмите Push

Как работает commit message

• Сообщение коммита обязательно (пустое значение нельзя отправить).
• По умолчанию SXL Studio не навязывает конкретный формат сообщения.
• Некоторые репозитории (особенно GitLab) проверяют формат на стороне сервера (например, Conventional Commits). Если формат не проходит политику, Push будет отклонён, а плагин покажет ошибку.

Все текстовые файлы нормализуются по trailing newline (POSIX-стандарт). Это исключает «фантомные» diff-ы на пустых строках, когда семантических изменений нет. Файлы, которые после нормализации оказались идентичны remote-версии, помечаются в списке маркером ≈ и открываются с пояснением вместо DiffEditor — так список Push остаётся прозрачным.

Если нечего отправлять, плагин покажет уведомление. Если есть токены, но не задан Tokens Path — покажет ошибку с подсказкой.

Scope changed: предупреждение при смене области подключения

Если после последнего Pull вы сменили в настройках подключения репозиторий, ветку, dataPath или tokensPath, Commit Modal покажет бейдж ⚠ Scope changed. Push при этом не блокируется отдельным подтверждением — оцените риск сами: обычно после смены scope сначала нужен Pull, иначе можно записать данные не в ту ветку/контекст.

#Pull — получение изменений

Soft Pull vs Hard Pull

Как сделать Pull

1. Нажмите кнопку Pull в нижней панели
2. Откроется Pull Modal с встроенным inline side-by-side diff:
   • Слева — список входящих файлов со счётчиком и статусами
   • Справа — Monaco DiffEditor: Local слева (текущее состояние), Remote справа (что придёт). Для новых файлов левая панель пуста — это и есть «добавлено»
   • Навигация: F7 / Shift+F7 между изменениями, кнопки-стрелки в правом верхнем углу
3. Ниже виден последний коммит удалённой ветки (автор, сообщение, время)
4. Нажмите Pull

Hard Pull

Если нужно полностью пересинхронизировать:

• Используйте Hard Pull из меню
• Все локальные данные и токены будут заменены содержимым из репозитория

Прогресс

Pull показывает прогресс по фазам:

• listing — сканирование дерева файлов
• data — загрузка данных
• tokens — загрузка токенов
• finalizing — финализация
• done — готово

Скорость при большом числе файлов

Загрузка данных и токенов выполняется параллельно (ограниченное число одновременных запросов к Git), чтобы ускорить Pull при больших деревьях без лишней нагрузки на провайдера. Если репозиторий очень большой, узким местом остаётся листинг дерева и сеть; при необходимости сузьте dataPath / tokensPath в настройках подключения.

При включённом Local Storage после каждого скачанного файла токены дополнительно пишутся на диск через HTTP на localhost — это обычно заметно быстрее, чем round-trip к GitHub/GitLab, поэтому ограничение по скорости по-прежнему задают листинг дерева и загрузка с провайдера. Держите Bridge на той же машине, где открыт браузер с Figma.

Если в Local Storage уже есть свежий snapshot для того же репозитория, ветки и путей, SXL Studio при запуске восстанавливает индекс workspace с диска и сначала проверяет только HEAD удалённой ветки. Если HEAD совпадает с последним синхронизированным коммитом, полный листинг/скачивание пропускается. Если HEAD изменился, Pull остаётся инкрементальным и скачивает только файлы с изменившимся Git SHA.

Автоэкспорт после Pull

Если в config.json задано autoExportOnPull: true, после Pull автоматически запускается экспорт токенов в Figma Variables.

#Ветки

Переключение ветки

1. Нажмите на имя текущей ветки в нижней панели
2. В меню появится список доступных веток
3. Выберите нужную ветку
4. Плагин обновит настройку подключения
5. Выполните Pull для синхронизации

Переключение ветки не загружает файлы автоматически — нужно сделать Pull. Первый Pull после смены ветки будет Hard Pull.

Создание ветки

Варианты создания:

1. Create Branch — создать от текущей ветки подключения.
2. Create Branch From... — выбрать любую исходную ветку и создать новую от неё.

После создания SXL Studio автоматически переключит активное подключение на новую ветку и обновит статус веток.

Создание ветки не загружает файлы автоматически. Сразу после создания/переключения выполните Pull.

#Индикаторы состояния

В нижней панели плагина отображается:

Авто-обновление статуса

• Фоновой polling — раз в 60 секунд, но не жёсткий setInterval: после каждого refresh (фонового, ручного или от локальных событий) следующий тик отсчитывается заново. Это убирает дубли вроде «нажал Refresh → через 5 секунд плагин сам делает ещё один запрос»
• Conditional GET. GitHub: ETag / If-None-Match → 304 Not Modified без расхода primary rate-limit. GitLab: сверка по head commit SHA ветки одним лёгким запросом → если SHA не поменялся, клиент переиспользует кешированное дерево без пагинации. В простое плагин стоит почти ничего
• Мгновенный refresh на возврате фокуса. Когда окно плагина снова становится видимым (visibilitychange → visible / focus), плагин триггерит check-git-status с throttle 10 секунд — это ускоряет реакцию Pull-индикатора на внешний push без лишних круговых запросов
• Любой ручной Refresh, как и фоновый polling/visibility trigger, идёт с принудительным обходом TTL-кеша дерева, но сохраняет conditional-проверку (ETag / head-SHA). Свежий коммит в ветке виден при ближайшем запросе, а не через два подряд пропущенных тика
• События от локальных операций (save, export, push, pull) сами вызывают triggerGitStatusRefresh() — никаких UI-roundtrip'ов
• Клиентская сторона кеширует GitClient на 60 секунд по ключу (connection, repo, branch, paths, token-signature), чтобы один Push или Pull не перечитывал дерево несколько раз
• При ручном или автоматическом refresh свежий список файлов дерева сразу кладётся в UI-снимок — inline-diff в Push/Pull модалках открывается без дополнительной загрузки и видит актуальные изменения, даже если юзер не открывал Git Browser

#Local storage (Bridge)

Лимит Figma clientStorage — порядка 5 MB на плагин. В больших token/data проектах эта квота может быстро закончиться.

Local Storage (переключатель в форме Sync для каждого подключения) сохраняет большие синхронизируемые данные на диск через SXL Studio Bridge:

1. Запустите Bridge (@sxl-studio/bridge 1.7.0+; для поля Cache folder и кнопки Open — 1.8.0+).
2. Включите Local Storage в форме подключения.
3. Если Bridge недоступен в момент Pull, Pull остановится до изменения локальных данных и попросит запустить Bridge.
4. Когда Bridge снова доступен, повторите Pull (или временно выключите Local Storage для этого подключения).

Безопасность: данные хранятся только на машине, где запущен Bridge.

Стандартные пути кэша

• macOS: ~/Library/Caches/sxl-studio-bridge/workspace-blobs
• Windows: %LOCALAPPDATA%\sxl-studio-bridge\Cache\workspace-blobs

Если задана переменная SXL_BRIDGE_WORKSPACE_BLOB_ROOT, Bridge использует путь из неё.

Поле Cache folder и кнопка Open

Начиная с Bridge 1.8.0, при включённом Local Storage у сохранённого подключения в форме Sync появляется поле Cache folder:

• показывает точный путь к локальному кэшу именно этого подключения на вашей машине;
• кнопка Open открывает эту папку в системном файловом менеджере (Finder на macOS, Explorer на Windows).

У каждого подключения свой подкаталог кэша (изолированно по repo/branch), поэтому несколько подключений не пересекаются. Это удобно, чтобы проверить, где физически лежат данные, или при необходимости очистить кэш вручную. Если Bridge не запущен или версия ниже 1.8.0, поле показывает подсказку запустить Bridge, а кнопка Open недоступна.

Опционально BRIDGE_AUTH_TOKEN включает защиту Bridge endpoints, если это требуется в вашей среде. Сгенерируйте длинный случайный локальный секрет, запустите Bridge с ним и укажите то же значение в поле подключения Bridge Auth Token, чтобы плагин мог читать/писать /api/status и /api/workspace-blob.

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
BRIDGE_AUTH_TOKEN=<generated_secret> sxl-bridge

Это поле не является GitHub/GitLab access token и не является Figma REST token. Если Bridge запущен без BRIDGE_AUTH_TOKEN, оставьте поле пустым.

Для Local Storage достаточно доступного Bridge; отдельная websocket-сессия Remote Connect для этого механизма не обязательна.

Перед Pull с Local Storage плагин проверяет GET /api/status, а затем читает/пишет крупные payload через /api/workspace-blob. Если включён BRIDGE_AUTH_TOKEN, оба запроса используют Bridge Auth Token из формы подключения.

После успешного Pull или Push SXL Studio сохраняет рядом с локальными данными лёгкий индекс workspace. При следующем запуске плагин быстро показывает известное состояние, затем делает дешёвую HEAD-проверку удалённой ветки. Если на remote ничего не изменилось, крупные файлы повторно не скачиваются; если ветка изменилась, скачиваются только изменённые файлы.

Если Bridge недоступен при включённом Local Storage, SXL Studio останавливает операцию до очистки или замены локальных данных и показывает понятное предупреждение. Запустите Bridge, проверьте порт/auth token и повторите действие.

Подробнее про Bridge: Утилита Bridge.

#Производительность и устойчивость

• Truncated tree protection. GitHub API у очень больших монорепо может отдать частичное дерево (флаг truncated). В этом случае SXL Studio не может гарантировать полноту списка удалённых файлов, поэтому Push и Pull блокируются и в нижней панели показывается баннер-предупреждение. Решение — сузить dataPath / tokensPath до реальных папок дизайн-системы
• Trailing newline нормализация. Все текстовые файлы (JSON, CSV, Vue, Code Connect) приводятся к единому виду с завершающим \n перед отправкой. Это убирает «фантомные» изменения в diff, когда разные редакторы ставят/не ставят последнюю пустую строку
• Только реальные удаления. Файл помечается как «удалённый» в модалке Push, только если он действительно существует на remote. Это защищает от ложных диффов после локальных rename/cleanup
• Полный diff для конфигов. Inline-diff покрывает не только токены и датасеты, но и code-connect.json, diff-id.*, diff-grid.*, config.json — так видно любое изменение, которое уйдёт в коммит
• Size guard для больших файлов. Файлы больше 1 МБ или длиннее 10 000 строк не подгружаются в inline DiffEditor — вместо этого показывается пояснение «Inline diff disabled». Сам файл по-прежнему попадает в коммит, просто его удобнее просматривать в IDE или UI провайдера. Это удерживает iframe плагина от фризов на тяжёлых JSON
• Noop filter. Если локальная и удалённая версии после нормализации идентичны, файл всё ещё отправится (Git-blob SHA отличается), но DiffEditor для него не открывается — вместо него короткий плейсхолдер. В списке такие файлы помечены маркером ≈

#Конфликты

SXL Studio не использует git merge. Синхронизация работает по SHA blob API:

• При Pull — локальные файлы перезаписываются содержимым с remote
• При Push — если на remote уже есть более новый коммит, API может вернуть ошибку

Рекомендация: используйте стандартный workflow — один человек делает Push, остальные Pull. Для параллельной работы используйте разные ветки.

#Связанные разделы

• Настройка GitHub — пошаговая инструкция для GitHub
• Настройка GitLab — пошаговая инструкция для GitLab
• Export Variables и Styles — автоэкспорт после Pull
• Миграция из Tokens Studio — конвертация token JSON и $themes.json