TurboExtensions

Расширенные возможности стилизации средствами CSS.

Инструменты разработчика

DevServer

Пререквизиты — node.js 8.x или nvm.

Установка:

git clone https://github.com/turboext/css.git
cd css
npm install
npm start

Локальный запуск тестов — npm test.

Возможности:

• автоматическое применение стилей без необходимости перезагружать страницу
• возможность открыть локальную бету на мобильном телефоне
• написание стилей в синтаксисе CSS или SCSS с использованием препроцессора postcss.

Использование:

Допустим, вы хотите поменя стили для сайта https://rozhdestvenskiy.ru. Порядок действий следующий:

• создать директорию hosts/rozhdestvenskiy.ru (дальше все действия будут происходить внутри этой директории);
• внутри этой директории создать файл HOSTS.yaml
• указать там название домен сайта, который используется в турбо-страницах:

- https://rozhdestvenskiy.ru

• создать файл style.css или style.scss
• запустить dev-server
• открыть http://localhost:3000 и выбрать адрес вашей турбо-страницы, например: https://rozhdestvenskiy.ru/, или https://yandex.ru/turbo?text=https://rozhdestvenskiy.ru/;
• внести изменения в файл стилей;
• изменения стилей будут применены автоматически.

Дополнительные возможности DevServer

• TURBO_HOST=https://some-host.yandex.ru npm start — возможность ходить за данными на отличный от https://yandex.ru сервер;
• &hostname=https://example.com — форсировать применение стилей для выбранного хоста, даже если url турбо-страницы отличается от него;
• &disable=1 — отключить подмену CSS (может быть удобно для тестирования страницы в iframe).

Livereload

По-умолчанию включён livereload режим, в котором изменения применяются автоматически без обновления страницы. Если с ним возникают сложности, нужно запустить сервер с переменной окружения LIVERELOAD=false:

• mac os x / linux — LIVERELOAD=false npm start
• windows — set LIVERELOAD=false && npm start

Отладка на мобильном телефоне

Существует два варианта:

• дождаться сборки автоматической беты в PR и использовать ссылки из описания PR
• для доступа к локальной бете с мобильного телефона можно использовать встроенное тунеллирование на базе ngrok:
  • mac os x / linux — PUBLIC=true npm start или npm run public
  • windows — set PUBLIC=true && npm start или npm run public

IFrame

Турбо-страницы могут отображаться внутри iframe, например в Поиске, поэтому рекомендуется смотреть на результат изменения стилей в iframe. В случае изменения каркаса страницы, могут возникнуть проблемы наличием горизонтального скролла. Убрать его можно следующим образом:

.ua_frame_yes .page__container {
    overflow-x: hidden;
}

Для тестирования страницы внутри iframe — нужно использовать адрес /frame, /frame-morda, вместо /turbo. Ссылки на iframe будут доступны в PR.

Прототипирование стилей в браузере

1. Установить расширенение live editor for CSS (или любое другое с похожими возможностями);
2. Зайти в браузере на турбо-страницу;
3. Написать CSS для нужных компонентов.

Ограничения

Ограничения указаны в конфиге stylelint:

• нельзя использовать пользовательские шрифты;
• нельзя использовать низкопроизводительную анимацию;
• нельзя использовать селекторы по имени тэга;
• нельзя использовать любые внешние ресурсы;
• размер CSS в gzip ограничен 21KB.

Deprecated

• Селекторы на .markup и его производные в скором времени перестанут работать

На code review могут быть указаны дополнительные требования к коду.

Важно: список ограничений может меняться со временем.

Технические детали сборки

• CSS код будет обработан с помощью postcss. Настройки можно посмотреть в конфигурационном файле.
• Минимальные версии поддерживаемых браузеров
  • android 4
  • iOS 9
  • IE 11
• Векторные изображения предпочтительнее растровых. Размер всех изображений должен быть оптимизирован до приемлемого уровня качества.

Для оптимизации SVG рекомендуется использовать svgo со следующими опциями: svgo -p 2 --multipass --enable=removeDesc --enable=removeTitle --enable=sortAttrs --enable=removeViewBox --enable=removeStyleElement -i [PATH_TO_SVG].

Создание PR

1. Сделать fork репозитория;
2. Создать директорию hosts/example.com;
3. В директории должно быть несколько обязательных файлов — HOSTS.yaml, OWNERS.yaml, style.css. Возможен вариант style.scss для использования синтаксиса SCSS.
   • HOSTS.yaml должен быть указан домен для которых будут применяться текущие стили, например:

     - https://rozhdestvenskiy.ru

   Протокол (http, https) обязателен. Фактически, это адрес сайта из https://webmaster.yandex.ru
   • OWNERS.yaml должен содержать список логинов на https://github.com кому разрешено править стили для текущего домена, например:

   - sbmaxx

4. Закоммитить изменения и создать PR в основной репозиторий. Желательно в тексте коммита указывать адрес сайта;
5. В описании PR добавьте несколько ссылок на ваши турбо-страницы;
6. Дождитесь создания автоматической беты. Ссылка на неё появится в описании PR через некоторое время после создания PR, проверьте на ней свои изменения;
7. Дождитесь прохождения линтеров;
8. Дождитесь прохождения ревью;

Когда я увижу это в production?

Изменения будут доступны в production в течение 30 минут после вливания PR в master ветку. В случае возникновения каких-либо проблем, пишите в slack, мы сможем помочь оперативно откатить изменения или внести правки.

Внесение изменений в инфраструктурную часть

1. Создать issue с описанием сути изменений;
2. Сделать branch в формате issues/<номер_issue>;
3. Закоммитить изменения и создать PR в основной репозиторий;
4. Связать PR и issue (например, c помощью комментария).

Поддержка разработчиков

https://turbosupport.slack.com, доступ по приглашениям.