@coraltravelcenter/b2c-landing-builder

Глобальный CLI для разработки B2C-лендингов через Tampermonkey и сборки CMS-готовых HTML-файлов.

Установка

Требуется Node.js 20.19 или новее.

npm install --global @coraltravelcenter/b2c-landing-builder

Builder устанавливается один раз и не копируется в проекты лендингов.

Команды

Команды выполняются из корня проекта:

b2c-landing-vite check
b2c-landing-vite dev
b2c-landing-vite build
b2c-landing-vite block:add hero
b2c-landing-vite block:rename hero main-hero
b2c-landing-vite update

• check проверяет конфигурацию, order.json и контракт JS-блоков.
• dev запускает Vite и userscript для Tampermonkey.
• build создаёт CMS-файлы в @CMS/ и переписывает пути ассетов на CDN.
• block:add создаёт файлы в выбранных форматах разметки и стилей.
• block:rename атомарно переименовывает все файлы блока и обновляет порядок.
• update проверяет npm registry и показывает команду ручного обновления.

Builder никогда не обновляется автоматически:

b2c-landing-vite update
# Update manually: npm install --global @coraltravelcenter/b2c-landing-builder@latest

Создание проекта

Новые проекты создаются отдельным пакетом:

npm create @coraltravelcenter/b2c-landing-vite

Репозиторий генератора: CoralTravelCenter/create-b2c-landing-vite.

Конфигурация

В корне каждого проекта находится landing.config.mjs:

export default {
  schemaVersion: 1,
  project: {
    name: "uae-promo",
  },
  site: {
    preset: "coral",
  },
  stack: {
    script: "vue",
    markup: "pug",
    styles: "less",
  },
};

Имя проекта должно соответствовать ^[a-z0-9][a-z0-9-]*$.

Поддерживаются:

• JavaScript: vanilla, vue;
• разметка: html, pug;
• стили: css, scss, less;
• сайты: coral, sunmar.

Зависимости выбранного стека устанавливаются локально в проект: vue и @vitejs/plugin-vue для Vue, pug для Pug, less для Less и sass для SCSS. Builder загружает Vue-плагин из проекта, поэтому Vue-зависимости не устанавливаются вместе с глобальным builder.

Monkey URL, контейнер и CDN prefix не задаются вручную:

• URL: https://<домен-пресета>/monkey/*;
• контейнер: #monkey-app;
• CDN prefix: landing-pages/<project.name>.

Production CDN Sunmar пока не настроен. dev и check доступны, но build завершается понятной ошибкой до добавления CDN в preset.

Структура проекта

src/
  order.json
  markup/
    welcome.html | welcome.pug
  styles/
    welcome.css | welcome.scss | welcome.less
  scripts/
    welcome.js
  components/       # только для Vue
public/
pug.rc               # только для Pug
landing.config.mjs
package.json

В проекте не нужны vite.config.js, исходники builder или локальные build-скрипты.

Порядок блоков

src/order.json является единственным источником порядка:

{
  "blocks": ["hero", "welcome"]
}

Для каждого ключа builder ищет разметку, стиль и необязательный JS-файл с тем же именем. Форматы определяются landing.config.mjs.

Контракт JavaScript

Если у блока есть src/scripts/<key>.js, файл обязан экспортировать функцию инициализации по умолчанию:

export default function hero() {
  const block = document.querySelector(".hero");
  if (!block) return;

  // Инициализация блока.
}

Builder вставляет разметку, затем вызывает функцию без аргументов. Скрипт блока сам находит свою разметку в document. Этот контракт одинаков для dev и CMS build; дополнительные контейнеры builder не создаёт. Блок без JS допустим.

Изображения

Изображения хранятся в public/ и используются от корня:

<img src="/hero.webp" alt="">

.hero {
  background-image: url("/hero.webp");
}

В dev пути направляются на http://127.0.0.1:5173. При production build они преобразуются в <assetsBase>/landing-pages/<project.name>/.... Builder переписывает только изображения jpg, jpeg, png, webp, avif, gif и svg; остальные root-relative ресурсы не изменяются.

Совместимость

Builder проверяет schemaVersion до запуска команд. Несовместимая версия схемы блокирует работу. Для аварийной сборки старого проекта можно использовать:

npx @coraltravelcenter/b2c-landing-builder@<version> build

Разработка пакета

npm ci
npm test
npm run check
npm run build
npm pack --dry-run

Pull request проверяется на Node.js 20.19 и 22. Prerelease публикуется с npm dist-tag next, стабильная версия — с latest.