smddds

В этом репозитории будет создана и настроена дизайн-система «Умной цифры».

Usage no npm install needed!

<script type="module">
  import smddds from 'https://cdn.skypack.dev/smddds';
</script>

README

Дизайн-система «Умной цифры»

В этом репозитории будет создана и настроена дизайн-система «Умной цифры».

Дизайн система построена с помощью библиотеки TSDX (https://www.npmjs.com/package/tsdx). Базовая конфигурация была подстроена под нужны разработки.

Команды

  • npm run start - работает для папки src, необходимо иметь файл index.tsx, в котором будет находится экспорт всех библиотечных компонентов. Необходимо для разработки.
  • npm run build - сборка билда в папке build.
  • npm run test - запуск тестов, результат выполнения будет записан в файл .jest-test-results.json, который необходим для storybook.
  • npm run test:env:setup - запустить тестовое окружение
  • npm run test:env:teardown - удалить тестовое окружение
  • npm run storybook - старт storybook (сначала нужно запустить npm run test, чтобы создался файл с результатами теста).
  • npm run storybook:build - билд сборка storybook.
  • npm run codegen - генерация новых компонентов

Разрабатывать компоненты можно двумя способами:

  1. Разработатывать их c помощью песочницы (/example), а затем писать для компонента story, которое отобразится в storybook. Для это необходимо сделать билд (npm run build), так как в песочницу компоненты вставляются из папки /dist - import {Component} from '../dist';. Песочница будет перерисовывать компоненты, если меняется компонент в папке /src. Для этого необходимо в корневой папке запустить команду npm run start.

Для того, чтобы запустить саму песочницу:

cd example
npm i
npm start
  1. Разрабатывать компоненты сразу вместе с storybook. Для этого нужна команда npm run storybook.

Создание новых компонентов

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

npm run codegen

С помощью данной утилиты можно создавать следующие сущности:

  • Публичные компоненты
  • Дочерние компоненты

Дочерние компоненты можно создавать на неограниченную вложенность. Например вы хотите создать компонент src/components/atoms/Foo/components/Bar/components/Baz. Для этого в имени родительского компонента нужно указать Foo/Bar а в имени дочернего - Baz.

Версионирование библиотеки

Версионирование библиотеки происходит автоматически согласно правилам семантического версионирования. В рамках задачи необходиомо иметь как минимум один коммит с тегом (feat, fix и тд). Если задача имеет "Breaking changes", то в соответствующем поле необходимо проставить Y. Если делать коммит через консоль, настроенные git hook`и выведут диалог, в котором можно будет выбрать необходимый тег. Если делать коммит через IDE, то можно скачать плагины, которые реализуют тот же механизм. Например для Webstorm - https://plugins.jetbrains.com/plugin/9861-git-commit-template/versions.

Публикация NPM

Для публикации необходимо:

  1. В терминале необходимо залогинится в nexus с помощью команды:
npm adduser --registry=https://nx.sm-digit.ru/repository/npm-smd-releases/
  1. Ввести логин, пароль, email (или сделать файл .npmrc, где прописать _auth и email)
  2. Команда npm publish

Инсталяция библиотеки

Создать в корне проекта файл .npmrc.

В нем прописать:

registry=https://nx.sm-digit.ru/repository/npm-all/
_auth=TOKEN
email=your_email

Команда для создания "TOKEN" - $ echo -n 'username:password' | openssl base64, где username - логин типа i.ivanov, password - ваш стандартный пароль.

После этого npm i smart-digit-design-system.

Внимание! Если вы никогда до этого не ходили в nexus, то нужно получить доступ у девопсов.

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

Качество кода контролируется с помощью ESlint, prettier, husky и lint-staged.

Тесты

Для запуска тестов на локальной машине должен быть установлен docker.

Тесты запускаются с использованием тестового окружения, которое разворачивается в docker-контейнерах:

  • browserless/chrome - Браузер Chrome, необходим для правильного кросплатформенного скриншот-тестирования.
  • nginx - Приложение с тестовыми кейсами. К данному приложению будет обращаться браузер при выполнении тестов.

Запустить тесты можно командой:

npm run test

В таком случае, тестовое окружение будет автоматически:

  • Запущено перед выполнением тестов
  • Остановлено и удалено после выполнения тестов

Так же, для отладочных целей, тестовое окружение можно запускать/останавливать отдельно от тестов:

  • Запуск окружения:
    npm run test:env:setup
    После запуска, тестовое приложение будет доступно по адресу: http://localhost:9338
  • Остановка и удаление окружения:
    npm run test:env:setup

В случае, если тестовое окружение уже запущено "вручную", то тесты можно запускать минуя автоматические этапы запуска/остановки окружения:

npm run test -- --no-env

Rollup

TSDX использует Rollup v1.x в качестве сборщика. См Optimizations.

TypeScript

.eslintrc.js и tsconfig.json необходимы для настройки линтера и typescript.

Оптимизация сборки

Разработчиками TSDX предусмотрены возможности кастомизации и оптимизации сборки. Нужно изучить tsdx optimizations docs. Можно также использовать invariant и warning.

Module

Поддерживаются CJS, ESModules и UMD.

Соответствующие пути настраиваются в package.json и dist/index.js.

Деплой песочницы (документация от разработчиков TSDX)

Песочница построена на Parcel, так что можно сделать сборку, если нужно. Гайд для ручной сборки с Netlify CLI (npm i -g netlify-cli):

cd example # переход в папку с песочницей
npm run build # билд песочницы
netlify deploy # деплой

В качестве альтернативы, если уже есть git-репозиторий, можно настроить непрерывное развертывание с помощью Netlify netlify init.

Именнованные экспорты (рекомендация от разработчиков TSDX)

Используйте только именованные экспорты. Единственным исключением является то, что инструмент требует экспорта по умолчанию (например, React.lazy(), Gatsby и Next.js).

Важные замечания и список доработок

  1. Для документации в storybook на данный момент (версия 5.3.12) функция <Props of={Button} /> не работает с HOC. Поэтому, если ваш компонент обернут в withStyle(style)(Component), то необходимо в файле со стори Component.stories.mdx сделать import Component, { Component as PureComponent} from './Component' и в Props пробрасывать именно PureComponent - <Props of={PureComponent} />.
  1. Если в props компонента указать кастомный объект (интерфейс), который импортируется через абсолютный путь, то storybook при генерации документации укажет в соответствующем поле description - any. Если же импорт сделать через относительный путь, то в description будет указано корректное описание.