npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hh.ru/bloko

v183.0.1

Published

hh.ru UI components

Downloads

1,992

Readme

Bloko - Библиотека компонентов hh.ru

Документация

Содержание:

  • Changelog
  • Зависимости
  • Установка зависимостей
  • Сборка проекта
  • Использование bloko в других проектах
  • Использование eslint правил блоко в других проектах
  • Разработка bloko
  • Встроенный сервер для тестирования документации
  • Версионирование bloko
  • Как собрать релиз bloko
  • Как собрать релиз bloko руками
  • Как подготовить ветку для тестирования с другим проектом
  • Вопросы-ответы

Версионирование bloko

Bloko использует semver.

Версии именуются по шаблону МАЖОРНАЯ.МИНОРНАЯ.ПАТЧ:

  • МАЖОРНАЯ версия — когда сделаны обратно несовместимые изменения API.
  • МИНОРНАЯ версия — когда добавлен новый функционал, не нарушая обратной совместимости.
  • ПАТЧ-версия — когда сделаны обратно совместимые исправления. Дополнительные обозначения для предрелизных и билд-метаданных возможны как дополнения к МАЖОРНАЯ.МИНОРНАЯ.ПАТЧ формату.

Changelog

Changelog проекта доступен в CHANGELOG.md

При разработке задачи, в папке changes/ нужно обязательно создать HH-{task}.md файл с описанием изменений, например: HH-55143.md. При сборке релиза содержимое файла будет автоматически добавлено в общий CHANGELOG.md. Информация о каждом изменении должна начинаться с символа *, чтобы после добавления в общий CHANGELOG.md получался список.

Зависимости

Для работы блоко-компонентов требуется:

  1. Синхронное подключение скрипта bloko/common/raw/htmlClasses.js до загрузки стилей. Этот скрипт проставляет в <html> глобальные классы, которые используются стилями.
  2. Библиотека core-js. Требуется версия не ниже 3.0.0-beta16, так как нужна поддержка URL + UrlSearchParams для urlParser
  3. Для lux компонентов, необходим react и react-dom

Сборщик:

  • yarn

Установка зависимостей

yarn install

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

Сборка осуществляется командой:

yarn build

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

Ниже перечислены основные задачи, которые понимает сборщик:

  • yarn build — создает новую полную сборку библиотеки и документации, запускает все проверки и тесты. Перед каждой новой сборкой предыдущая папка build удаляется со всем ее содержимым. Данный таск запускает по умолчанию минификацию css, оптимизацию картинок.
  • yarn build-watch — создает новую сборку и затем запускает вотчер. Также вотчится документация lux компонентов и используется hot reload.
  • yarn test — запускает все юнит-тесты.
  • yarn clean — удаляет старую сборку, а именно полностью удаляет папку build со всем ее содержимым.
  • yarn lint — запуск линтинга.
  • yarn jest — запускает только jest юнит-тесты
  • yarn jest -u — обновляет снепшоты для юнит тестов, которые используют снепшоты
  • yarn styleguide — запускает lux документацию на отдельном порту, автоматически работает hot-reload.

Использование bloko в других проектах

Чтобы подключить блоко нужно:

  1. Добавить зависимость yarn add @hh.ru/bloko;
  2. В сборке добавить процессинг для бабеля папки node_modules/@hh.ru/bloko;
  3. Подключить raw bloko скрипты (bloko/raw) на страницу до остальных скриптов.

Использование eslint правил блоко в других проектах

Для подключения правил из модуля eslint-rules в свой проект нужно:

  1. Установить плагин eslint-plugin-local-rules:
    yarn add eslint-plugin-local-rules
  2. Создать в корне проекта модуль ./eslint-local-rules.js, экспортирующий объект с правилами:
    'use strict';
    module.exports = require('@hh.ru/bloko/eslint-rules');
  3. Добавить плагин eslint-plugin-local-rules и указать необходимые правила в конфиг eslint (пример для .eslintrc);
    {
        "plugins": ["local-rules"],
        "rules": {
            "local-rules/bloko-no-class-name-literals": ["error"],
            "local-rules/bloko-use-selectable-attributes": ["error"]
        }
    }

eslint-baked-rules

Для правила bloko-use-selectable-attributes генерируется конфиг eslint-rules/baked-rules-config.json, собирающий информацию о текущих компонентах.

Он добавляется/обновляется в репозитории автоматически при релизе и необходим для правильной работы правила. В файле хранится мэппинг перечисляемых props к атрибутам компонентов. При добавлении нового или изменении PropTypes существующего компонента, можно протестировать правильность генерации этого конфига, выполнив команду gulp eslint-baked-rules.

Разработка bloko

Любые изменения в репозитории должны проходить под определенной задачей в jira. Обязательна практика создания pull request для ревью.

Встроенный сервер для тестирования документации

yarn storybook

Как собрать релиз

Hornet полностью поддерживает автоматизированную сборку bloko.

Как собрать релиз руками

Предположим у нас есть ветка HH-12345.

git fetch --tags
git checkout master
git reset --hard origin/master
git merge --no-ff --no-edit HH-12345
yarn install
yarn prepare-release
yarn version --new-version [patch | minor | major] --no-git-tag-version
git add -A
git commit --no-verify -m "release <версия> [ваша.почта@hh.ru]"
git push --tags origin master <версия>
git checkout -b build-<версия>
yarn release
git add -f build
git commit --no-verify -m "build-<версия> build directory"
git push origin build-<версия>

После этого пишем письмо на [email protected] о выходе нового релиза.

Как подготовить ветку для тестирования с другим проектом

Находясь в нужной feature-ветке (например, HH-12345):

yarn push-test-branch

На основе текущей ветки HH-12345 выполняет команду, которая собирает тестовую ветку HH-12345-testing, которая подготовлена к релизу таской prepare-release и содержит папку build. Команда вернет версию блоко вашей ветки, например:

npm-зависимость для проекта:
git+ssh://[email protected]/hhru/bloko.git#35a45e6a99e37461ad472df2f8d26dafb794d6ca
ветка:
HH-12345-testing

Обновить у соответствующего проекта версию bloko:

yarn add git+ssh://[email protected]/hhru/bloko.git#35a45e6a99e37461ad472df2f8d26dafb794d6ca

Вопросы-ответы

Можно ли выпускать несовместимую с одним из клиентов (клиент — проект-пользователь библиотеки) версию? Нужно ли при выпуске bloko для одного клиента тестировать все остальные клиенты и править их или заниматься этим будет тот, кому это понадобится?

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

При выпуске bloko тестируется и выпускается только тот клиент, под который сделаны изменения. Остальные клиенты тестируются и переводятся на новую версию теми, кому это понадобится.

Можно ли добавлять в bloko компоненты, использующиеся только одним клиентом? Какие критерии переноса компонента в bloko?

Перед тем, как добавить какой-либо компонент в bloko, нужно посоветоваться с Мишей Калашником.

Если попробовать кратко сформулировать — в bloko уносим всё, что относится к проекту в целом, а не к конкретной странице.

Как быть, если один и тот же компонент захочет выглядеть или работать в разных клиентах по-разному?

bloko ничего не знает про клиентов, использующих библиотеку, поэтому внесение клиенто-зависимой логики в проект не допускается.

В некоторых ситуациях допускаетcя стилизация медиа-выражениями или изменение стиля/логики работы модами, такие ситуации обсуждаются отдельно.