В наши дни библиотеки компонентов в моде, и многие компании развертывают свои собственные решения или придерживаются множества альтернатив с открытым исходным кодом. Использование библиотеки компонентов для разработки пользовательского интерфейса, особенно в больших командах, дает много больших преимуществ. Он позволяет в полной мере использовать преимущества модульных и повторно используемых компонентов пользовательского интерфейса, что увеличивает скорость разработки и унифицирует стили для нескольких команд и приложений. Добавьте к этому надежную систему проектирования, и переход от дизайнеров к командам разработчиков станет более плавным и эффективным.
Фреймворки / библиотеки, такие как React, Vue и т. Д., Идеально подходят для этой цели, поскольку они разработаны как модульные. В этом посте React и стилизованные компоненты используются в качестве основных инструментов для разработки компонентов.
Есть также несколько полезных инструментов, которые можно использовать для ускорения процесса разработки и развертывания библиотеки. Применяя модульный подход, было бы разумно, чтобы каждый компонент был собственным пакетом npm, а вся библиотека была монорепозиторием. Именно здесь Lerna будет использоваться для управления несколькими пакетами внутри проекта, а также для отслеживания их версий и процесса публикации.
Для тестирования и документирования компонентов используется Docz (как альтернатива Storybook). Он позволяет документировать компоненты с помощью MDX, который представляет собой формат, сочетающий JSX и Markdown, что в основном позволяет импортировать компоненты React внутри файлов Markdown. Кроме того, Docz версии 2 работает на GatsbyJS, что увеличивает скорость разработки и сборки и обеспечивает доступ к обширной сети плагинов и инструментов Gatsby.
Настройка Лерны
Мы начнем с создания нового проекта под названием uikit и установки необходимых зависимостей.
$ npm i -g lerna $ mkdir uikit && cd $_ $ yarn add docz react react-dom styled-componentsПосле установки основных зависимостей пора инициализировать проект Lerna.
$ lerna initЭто создаст следующую структуру проекта:
ui-kit/ packages/ package.json lerna.json
Компоненты пользовательского интерфейса будут храниться в папке packages.
Теперь давайте рассмотрим сгенерированный lerna.json, который служит файлом конфигурации для Lerna. По умолчанию ничего особенного не происходит, и после нескольких настроек конфигурация будет выглядеть следующим образом.
{
"npmClient": "yarn",
"version": "independent",
"packages": [
"packages/*"
],
"useWorkspaces": true
}
Самыми важными изменениями здесь являются выбор yarn в качестве клиента npm, указание independent управления версиями, чтобы версии пакетов можно было изменять независимо друг от друга, и включение Рабочих пространств пряжи. Параметр packages указывает на расположение пакетов нашей библиотеки, для которого мы сохраним настройку по умолчанию. Более обширный список параметров конфигурации доступен на странице Github Лерны.
Кроме того, нам нужно будет добавить параметры, связанные с рабочими областями, в корень package.json.
{
"name": "uikit",
"license": "MIT",
"workspaces": {
"packages": [
"packages/*"
]
},
"private": true,
"dependencies": {
"docz": "^2.2.0",
"lerna": "^3.20.2",
"react": "^17.0.1",
"react-dom": "^17.0.1",
"styled-components": "^5.0.0"
},
"devDependencies": {
"prettier": "^2.1.2"
}
}
Здесь мы указываем путь к workspaces, который совпадает с путем в lerna.json. Также мы должны сделать пакет приватным, иначе рабочие области не будут работать.
Создание первого компонента
Чтобы начать работу с разработчиками, давайте добавим первый пакет - Typography с необходимыми компонентами базового шрифта. В результате структура проекта будет обновлена следующим образом.
ui-kit/
packages/
typography/
src/
index.js
CHANGELOG.md
package.json
package.json
lerna.json
Прежде чем писать компоненты шрифта, давайте внесем несколько изменений в package.json типографики.
{
"name": "@uikit/typography",
"version": "1.0.0",
"description": "Base fonts",
"main": "dist/index.js",
"module": "src/index.js",
"files": [
"dist",
"CHANGELOG.md"
],
"author": "",
"license": "MIT"
}
Наиболее интересными здесь являются поля main, module и files. Мы укажем main на папку dist, где будут храниться перенесенные файлы, которые позже будут использоваться в установленном пакете. module будет указывать на папку src, поэтому пакеты можно импортировать непосредственно из исходной папки во время разработки, и изменения будут отражены немедленно, без необходимости повторной загрузки пакетов или запуска сценария сборки. Наконец, свойство files содержит список файлов, которые будут включены в опубликованный пакет.
Теперь мы можем настроить некоторые основные стили шрифтов в typography's index.js. Они будут выполнены в виде стилизованных компонентов.
Обратите внимание, что помощник css из styled-components используется для определения многоразовых частей стилей, которые затем расширяются другими компонентами. Компоненты также принимают свойство fontWeight для настройки, которое по умолчанию равно regular.
Попробовать детскую площадку Docz
Похоже, сейчас самое время опробовать эти компоненты в действии, и именно здесь Docz будет использоваться для документирования их использования. Для этого нам нужно добавить где-нибудь в проекте файл .mdx с документацией по компоненту, и один из этих файлов должен указывать на route: / и будет использоваться в качестве первой страницы. Давайте создадим этот index.mdx в корне packages.
// index.mdx --- name: Welcome route: / --- # Welcome to the awesome UI Kit Select any of the components from the sidenav to get started.
После запуска yarn docz dev мы можем перейти к localhost:3000 и увидеть первую страницу библиотеки.
Чтобы добавить документацию к типографике, мы создадим папку docs внутри пакета и добавим туда typography.mdx.
ui-kit/
packages/
typography/
docs/
typography.mdx
src/
index.js
CHANGELOG.md
package.json
package.json
lerna.json
Для документирования компонентов мы будем использовать специальный компонент Docz, который называется Playground. Обтекание им компонентов позволит редактировать их прямо под тем местом, где они отображаются.
---
name: Typography
menu: Components
---
import { Playground } from 'docz';
import { H1, H2, H3, H4, H5, H6, Text, SmallText } from '../src/index';
# Base Typography
<Playground>
<H1>Heading 1</H1>
<H2>Heading 2</H2>
<H3>Heading 3</H3>
<H4>Heading 4</H4>
<H4 fontWeight='bold'>Heading 4 bold</H4>
<H5>Heading 5</H5>
<H6>Heading 6</H6>
<Text>Text</Text>
<SmallText>SmallText</SmallText>
</Playground>
После обновления страницы или перезапуска сервера разработчика, если необходимо, мы сможем увидеть наши компоненты типографики. И самое лучшее, что мы можем напрямую редактировать код на странице и сразу видеть обновленные результаты!
Добавление пользовательских шрифтов
Это хорошо работает для встроенных шрифтов, но что, если мы хотим загрузить собственный шрифт, скажем, из шрифтов Google? К сожалению, поскольку версия 2 Docz представляет собой серьезную переработку версии 1, до сих пор нет четкого и задокументированного способа сделать это. Однако есть одно решение, которое также наглядно демонстрирует расширяемость конфигурации Gatsby и концепции, известной как Component shadowing.
Для компонентов, специфичных для Gatsby, нам нужно создать src папку в корне проекта, где, среди прочего, будут храниться специфические для темы компоненты. Поскольку мы расширяем gatsby-theme-docz, папку с этим именем необходимо создать внутри src. Наконец, мы создадим внутри него wrapper.js файл, чтобы иметь следующую структуру проекта.
ui-kit/
packages/
typography/
docs/
typography.mdx
src/
index.js
CHANGELOG.md
package.json
src/
gatsby-theme-docz/
wrapper.js
package.json
lerna.json
Внутри wrapper.js мы добавим очень простой компонент, единственная задача которого - передать его дочерние элементы.
Кажется совершенно бессмысленным создавать компонент, который только пересылает потомков, однако причина этого в том, что теперь мы можем включить css стилей в этот компонент, который будет применяться глобально. Для этого создадим styles.css рядом с wrapper.js и импортируем туда один из выбранных шрифтов. В этом руководстве мы будем использовать Монсеррат.
Теперь нам просто нужно импортировать этот файл в wrapper.js и обновить константу fontFamily для типографики.
Изменения должны быть видны сразу (в противном случае перезапустите сервер разработки). Возможно, это не самый чистый подход, но он выполняет свою работу, и, поскольку больше невозможно загружать пользовательские шрифты через doczrc.js, это может быть одним из немногих жизнеспособных решений.
Настройка сайта документации
Кстати о doczrc.js, который используется для настройки проекта Docz. Список параметров конфигурации можно найти на сайте документации проекта. Поскольку сейчас мы используем Montserrat для типографики набора пользовательского интерфейса, было бы разумно, если бы на нашем веб-сайте документации использовался тот же шрифт. Для этого мы добавим свойство themeConfig в doczrc.js, где будут применяться стили для наиболее часто используемых текстовых элементов.
Поскольку нам нужно хранить конфигурацию нашего проекта отдельно от компонентов, нам придется объявить семейство шрифтов отдельно и использовать его для определенных текстовых элементов. Кроме того, мы можем настроить название и описание проекта. Значение по умолчанию themeConfig можно найти на странице Docz на Github. Дополнительные возможности настройки проекта, например добавление собственного логотипа, описаны в документации.
Добавление кнопок
Наконец, пришло время добавить компонент React, Buttons,, который также будет использовать типографику для лучшей иллюстрации того, как компоненты могут использоваться вместе. Как и раньше, мы сделаем новый пакет, поэтому структура проекта будет следующей.
ui-kit/
packages/
typography/
docs/
typography.mdx
src/
index.js
CHANGELOG.md
package.json
buttons/
docs/
buttons.mdx
src/
index.js
Buttons.js
CHANGELOG.md
package.json
src/
gatsby-theme-docz/
style.css
wrapper.js
package.json
lerna.json
package.json для buttons будет выглядеть почти так же, как typography, за некоторыми небольшими исключениями. Наиболее примечательным является то, что buttons имеет typography пакет в качестве зависимости.
{
"name": "@uikit/buttons",
"version": "1.0.0",
"description": "Button components",
"main": "dist/index.js",
"module": "src/index.js",
"files": [
"dist",
"CHANGELOG.md"
],
"dependencies": {
"@uikit/typography": "^1.0.0"
},
"author": "",
"license": "MIT"
}
Теперь, после того, как мы запустим lerna bootstrap, он установит все необходимые пакеты и создаст символическую ссылку на зависимости внутри папки packages. Одним из хороших преимуществ этого является то, что если мы внесем какие-либо изменения в пакет typography и будем использовать этот пакет внутри buttons, изменения будут немедленно отражены в обоих пакетах без необходимости перестраивать или публиковать какие-либо из них. Это делает процесс разработки действительно быстрым и эффективным!
После того, как все зависимости были установлены, мы можем приступить к написанию кода для кнопок.
Здесь мы определяем два основных компонента кнопки. Компонент со стилем Button имеет несколько базовых стилей, которые можно расширить. ButtonSmall имеет предопределенный текстовый компонент и поэтому принимает текст кнопки как отдельную опору. Кроме того, для удобства мы экспортируем все из Buttons.js в index.js. Это обеспечит единую точку экспорта для каждого пакета, что особенно полезно, когда в пакете несколько файлов. Теперь давайте опробуем эти новые компоненты на игровой площадке.
// packages/buttons/docs/buttons.mdx
---
name: Buttons
menu: Components
---
import { Playground } from 'docz';
import { Button, ButtonSmall } from '../src/index';
# Buttons
## Base button
<Playground>
<Button>Test</Button>
</Playground>
## Small button
<Playground>
<ButtonSmall text='Click me'/>
</Playground>
Вернувшись к localhost:3000, мы можем убедиться, что кнопки работают должным образом. Благодаря этому у нас есть правильно задокументированная работающая библиотека компонентов, которую можно легко расширить.
Развертывание документов и пакетов публикации
До сих пор мы фокусировались в основном на стороне разработки библиотеки компонентов, однако есть несколько других важных шагов, которые необходимо выполнить, прежде чем библиотека станет пригодной для использования.
Публикация пакетов
Чтобы опубликовать все пакеты, которые были изменены с момента последней публикации (и после того, как они были перенесены с помощью Babel), мы можем использовать команду lerna publish. Перед публикацией будет предложено указать версии для каждого пакета. Версия может быть указана напрямую с помощью команды publish, которая применит одинаковое управление версиями ко всем измененным пакетам и пропустит запросы, например lerna publish minor. Чтобы публикация работала, необходимо добавить registry в lerna.json.
"command": {
"publish": {
"registry": "https://mypackageregistry/"
}
}
Создание документов и их обслуживание
Docz поставляется с несколькими встроенными скриптами, которые упрощают просмотр и развертывание документации. Его можно создать и обслужить локально, запустив yarn docs build && yarn docz serve. Для развертывания документации в Интернете на сайте Docz есть удобный пример сделать это с помощью Netlify. После того, как сайт Netlify настроен, его легко развернуть, запустив netlify deploy --dir .docz/dist.
Если вы хотите взглянуть на шаблонный код библиотеки компонентов, он доступен на Github.
Понравилась эта статья? Если да, то получите больше похожего контента, подписавшись на наш канал YouTube в Decoded!
Первоначально опубликовано на https://claritydev.net.
