Пользовательские турбо-компоненты

Репозиторий с кодом пользовательских компонентов, которые могут быть использованы на Турбо-страницах.

Содержание

• Начало разработки
  • Клонирование репозитория
• Создание своего компонента
  • Структура директории с блоками
  • Написание своего примера
  • Ограничения
  • Написание кода
  • Отладка кода
• Процесс разработки
• Релизный процесс (когда я окажусь в production?)
• Работа с линтерами и CI
• Вопросы и проблемы

Начало разработки

Клонирование репозитория

Для начала необходимо выполнить команды:

git clone [email protected]:turboext/components.git components
cd components
npm i
npm start

Проверяем работу репозитория: переходим на http://localhost:8081/render/ext-exchange-rates/default.

Создание своего компонента

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

Структура директории с блоками

Для его создания необходимо соблюдать соглашение по наименованию:

components/
└── ExtFancyButton
    ├── ExtFancyButton.examples
    │   └── default.xml
    ├── ExtFancyButton.scss
    └── ExtFancyButton.tsx

То, есть все кастомные блоки лежат в корневой директории components.

Отдельный блок имеет свою директорию, начинается с Ext и используют pascal case для наименования.

Например, в данном случае:ExtFancyButton — директория с блоком.

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

Например, в данном случае:ExtFancyButton.tsx — файл входа в блок (будет вызван с пришедшими данными на сервере и гидрирован на клиенте).

<Component-Name>.examples - директория с примерами данных для отображения блока. Используется для отладки.

Например, в данном случае:ExtFancyButton.examples — директория с примерами к блоку.

Примеры именуются свободно, и имеют расширение .xml

Например, в данном случае: default.xml — единственный пример для блока.

Написание своего примера

Все примеры описываются в xml формате, как содержимое rss-файла. Пример:

<ExtExchangeRates data-rates='["USD","EUR","CHF","GBP","JPY","AUD","CZK"]'></ExtExchangeRates>

Данные можно передавать с помощью data-аттрибутов, в компонент они придут как пропсы с такими же названиями, но сериализованные для удобства:

• Если в качестве значения передана строка, которая сериализуется в число (например, "123" или "123.123"), то в качестве аргумента в компонент будет передано число
• Если в качестве значения передана строка, которая сериализуется в объект (не примитив), то в качестве аргумента будет передан объект (например, '{"a": "b"}' или '["USD","EUR"]').
• В иных случаях в качестве значения будет передана строка.

Ограничения

Disclamer

Правила разработки находятся в развитии и могут быть изменены в будущем.

Если вы хотите делать ajax запросы, то их возможно совершать только к API, находящемуся на одном домене с вашим сайтом. Например: для сайта rozhdestvenskiy.ru можно совершать ajax запросы только к домену rozhdestvenskiy.ru Запросы, например, к aws.com будут заблокированы политиками CSP При этом надо использовать CORS и нельзя передавать Cookie yandex.ru домена.

Запрещается работать с window.location и window.open.

Использование пользовательского компонента не подразумевает под собой размещение рекламы в каком-либо виде. Для обеспечения надлежащей работы Турбо-страниц при размещении рекламы на Турбо-страницах необходимо использовать специальные форматы рекламных блоков, которые доступны в интерфейсе ADFOX(1) или РСЯ(2), и интерфейс Яндекс.Вебмастера для указания соответствующих идентификаторов блоков.

1 – ссылка на хелп ADFOX https://yandex.ru/support/adfox-sites/code/adfox-turbo.html 2 – ссылка на хелп Вебмастера https://yandex.ru/dev/turbo/doc/settings/ads-docpage/

Встраиваемые виджеты (embed widgets)

Для создания компонентов-виджетов, загружающих для своей работы внешние скрипты, необходимо использовать существующий компонент ExtEmbed (документация).

Написание кода

Все блоки пишутся строго на typescript. Точка входя для блока должна экспортировать class или простую (не стрелочную) функцию, названные так же, как и компонент.

Валидные записи:

export class ExtExchangeRates extends React.PureComponent<IProps> {}

export function ExtExchangeRates () {}

Невалидные записи:

export const ExtExchangeRates = () => {}

export default function ExtExchangeRates () {}

При импорте он будет вызван как реакт-компонент, а в качестве пропсов ему будут переданы данные из rss. Внутри компонента можно импортировать стили, которые приедут вместе с ним.

Отладка кода

Код компонента доступен по ссылке /render/<component-name>/<example-name>. Список всех примеров можно посмотреть на заглавной странице.

Процесс разработки

1. Для разработки вы создаете форк проекта.
2. Вы создаете pull-request в репозиторий
3. Проходят все линтеры. Если линтеры не проходят, пулреквест не рассматривается. Если есть проблемы, связанные с линтингом файлов (например, конфликтующие линтеры или ошибки во время линтинга кода), необходимо создать issue.
4. После того, как прошли все линтеры, пулреквест получает два апрува от команды.
5. Пулреквест вливается в репозиторий.

Релизный процесс (когда я окажусь в production?):

1. Отведение новой релизной ветки происходит автоматически в пятницу вечером.
2. За выходные все кастомные блоки тестируются.
3. Если все хорошо, то выпускаем новую версию пакета компонентов. Если есть проблемы с отдельными блоками, то эти блоки не будут включены в релиз.
4. Релиз с компонентами попадают на страницы в понедельник.
5. Изменения будут появляться в CHANGELOG.md

Работа с линтерами и CI

Мы используем много самых разнообразных линтеров для контроля качества кода.

• Для контроля стилей (.scss) мы используем stylelint.
• Для контроля наименования мы используем линтер файловой структуры
• Для контроля типов мы используем tsc.
• Для контроля качества кода мы используем eslint с рядом плагинов.

Часть из них запускается перед коммитом, часть — перед пушем в удаленный репозиторий.

Если линтер падает на прекомите, можно сначала попробовать поправить изменения автоматически с помощью команды: npm run lint:fix.

Вопросы и проблемы

В случае каких-либо проблем или вопросов вы можете создать issue.