Упаковка и публикация темы

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

Сборка#

php artisan cartix:theme-build my-theme
php artisan cartix:theme-build my-theme --output=/путь/my-theme.zip

По умолчанию архив ложится в storage/app/dist/themes/<id>-<версия>.zip. Команда печатает размер, число файлов, отпечаток пакета и готовую строку для регистрации выпуска.

Сборка откажется, если:

• в папке нет theme.json;
• theme.json не читается как JSON;
• не заполнено id, name или version;
• id внутри файла не совпадает с именем папки.

Последнее важно: адрес темы в маркетплейсе — это и есть её идентификатор, и установщик у клиента их сверяет. Пакет, подписанный под другую тему, он ставить откажется.

Что попадает в пакет#

Все файлы темы, кроме:

• служебных папок: .git, node_modules, .github, .idea, .vscode;
• служебных файлов: .env, .DS_Store, Thumbs.db, .gitignore;
• assets/plugins/ и templates/plugins/.

Последнее — не мелочь. Эти папки наполняют установленные у клиента дополнения: там лежат их шаблоны и стили. Они принадлежат его магазину, а не вам. Попади они в пакет — установка вашей темы затёрла бы его блоки.

Про эти папки волноваться не нужно: когда клиент поставит дополнение, оно само положит туда свои файлы. Ваша задача — оставить в разметке точки встраивания там, где им место.

⚠️ Пустая папка в архив не попадает — складывается список файлов. Завели assets/css/ без единого файла — у клиента этой папки не будет.

Версия магазина, на которую рассчитана тема#

"requires": { "core": "2.0.0" }                            эта версия и новее
"requires": { "core": ">=2.0.0" }                          то же, со знаком
"requires": { "core": { "min": "2.0.0", "max": "3.0" } }   с верхней границей

Обычный случай — только нижняя граница.

Ставьте ту версию, возможностями которой тема действительно пользуется, и убедитесь, что эта версия магазина уже вышла. Иначе клиент купит тему, которая не установится.

Проверка идёт до подмены папки, поэтому отказ безопасен: прежняя тема остаётся на месте, магазин работает, а владелец видит понятное сообщение о том, что сначала нужно обновить магазин.

Выкладка в маркетплейс#

cartix:theme-build my-theme
# → загрузить архив на Store, завести карточку темы в каталоге
cartix:release-register my-theme 1.2.0 путь/к/my-theme-1.2.0.zip --publish

Пакет подписывается при регистрации, и установщик у клиента проверяет подпись. Без регистрации выпуска клиент тему не получит — файлы тем в магазин не входят.

У каждого выпуска должно быть «что нового» на всех языках карточки. Владелец видит эти строки при обновлении, и выпуск без объяснения выглядит как «что-то поменяли, а что — неизвестно». Пишите о том, что владелец получает, а не о том, какой файл поправили.

Как проходит обновление у клиента#

Новая версия сначала полностью раскладывается рядом — покупатели в это время видят старую тему, — и только потом папки меняются местами. Сбой на любом шаге возвращает прежнюю тему, и магазин продолжает работать.

После замены скомпилированные шаблоны сбрасываются сами. Папки assets/plugins/ и templates/plugins/ переносятся из прежней версии в новую — иначе после обновления витрина потеряла бы блоки установленных дополнений.

Что переживает обновление, а что нет#

Настройки темы переживают. Они лежат у витрины в базе, а не в файлах: по совпадающим ключам новая версия увидит всё, что владелец настроил.

⚠️ Правки владельца в файлах темы теряются. Папка заменяется целиком. Скажите об этом в описании темы прямым текстом.

Правильный ответ владельцу, который хочет и менять вёрстку, и получать обновления: он делает копию вашей темы и живёт с ней. Копия независима — правки в ней в безопасности, но и обновления оригинала в неё не приходят. Другого способа нет: наследования между темами не существует, копия всегда полная.

Правило автора темы: не переименовывайте ключи настроек#

Переименовали primary_color в primary — владелец получит цвет по умолчанию вместо своего и решит, что обновление сломало магазин.

Нужно новое поведение — заводите новый ключ, а старый оставляйте работать. Для нового поля обязательно задавайте значение по умолчанию: оно подставится само, и после обновления тема не встретит владельца пустотой.

Описание темы в маркетплейсе#

Описание говорит, что тема даёт магазину, а не как она устроена внутри. Обещать то, чего в теме нет, нельзя — это видно клиенту сразу после покупки.

Пишите обычными предложениями, обращаясь к читателю на «вы»: «Вы задаёте цвета и ширину прямо в панели, не трогая файлы», а не «поддерживается настройка палитры».

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

Что стоит сказать в описании отдельно#

• какие языки в теме есть готовыми;
• рассчитана ли она на конкретную товарную нишу;
• что правки в файлах теряются при обновлении и для правок делают копию;
• если тема подключает что-то извне — прямо об этом.

Установка темы из файла#

Раздел «Платформа» → «Установка и обновления» → «Установка файлом».

⚠️ Сейчас этот экран не доводит установку до конца. У файла с диска нет подписи маркетплейса, поэтому магазин требует осознанного подтверждения владельца, а кнопки подтверждения на экране нет. Загрузка заканчивается сообщением о том, что файл не подписан.

Сама установка при этом исправна: она ставит тему и правильно отказывает теме, которая требует магазин новее. Пока экран не доделан, тему на чужой магазин кладут папкой или ставят из маркетплейса.