Мощное живое руководство по стилю для компонентов React.

В предыдущих историях я привел несколько причин, по которым я использую экосистему React (№1) и Стилизованные компоненты (№2) для создания веб-приложений и мобильных приложений.

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

Зачем мне вообще создавать какое-либо руководство по стилю?

Такой инструмент дает вам:

  1. Визуальный обзор всех имеющихся у вас компонентов.
  2. Документирование и разбивка компонентов на логические группы.
  3. Площадка, где можно попробовать всевозможные варианты реквизита и контента.

Мой любимый инструмент - React Styleguidist.

Конечно, есть и другие замечательные инструменты. Например, Сборник рассказов. Его преимущество в том, что помимо React он поддерживает также другие JavaScript-фреймворки, такие как Angular или Vue.

Я просто придерживаюсь Styleguidist, потому что в нем есть все, что мне нужно.

Установка и настройка

Если вы начали свой проект с помощью Create React App, то вам просто нужно выполнить эту простую команду:

npm install --save-dev react-styleguidist

Если вы начали свой проект с использованием других инструментов или настроек, вам также необходимо:

Наконец, запустите руководство по стилю с помощью этой команды:

npx styleguidist server

И откройте его в своем браузере:

http://localhost:6060

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

Создайте styleguide.config.js файл в корневой папке вашего проекта. Вы можете настроить руководство по стилю в соответствии со своими потребностями. Вы можете изменить номер порта по умолчанию, основной заголовок руководства по стилю, разделы компонентов и многие другие параметры.

Начните документировать свои компоненты

Рекомендую прочитать официальную документацию. Всего несколько советов от меня.

Реквизит и комментарии

Первая часть документации автоматически генерируется из PropTypes и комментариев к коду (JSDoc).

/**
 * Description of the component if needed
 */
const Button = props => (...);
Button.propTypes = {
  /** No user action on button is allowed */
  disabled: PropTypes.bool,

  /** Primary theme color */
  primary: PropTypes.bool,

  /** Shadow effect */
  raised: PropTypes.bool
};

Button.defaultProps = {
  disabled: false,
  primary: false,
  raised: false
};

Компонент выше даст такой четкий вывод в руководстве по стилю:

Живые примеры

Вторая часть документации - это живые редактируемые примеры, созданные с использованием файлов Markdown.

components/
  Button/
    Button.js
    Button.md

Styleguidist по умолчанию ищет файлы Readme.md или ComponentName.md.

```jsx
  <Button primary>Click me!</Button>
```

Результат выглядит так:

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

Styleguidist по умолчанию находит и анализирует компоненты JSX. Но он может легко обрабатывать также стилизованные компоненты с помощью простого трюка.

Вам просто нужно явно указать, что является компонентом:

const Button = styled.button``;
/* @component */
export default Button;

Настроить видимое имя

Возможно, вам потребуется изменить имя компонента, используемого в руководстве по стилю:

/**
 * @visibleName Default Button
 */
const Button = props => (...);

Классификация компонентов

Когда ваше руководство по стилю будет расти, может оказаться полезным разделить компоненты на категории. Вы можете сделать это в styleguide.config.js файле.

module.exports = {
  ...
  sections: [
    {
      name: 'Basics',
      components: 'src/basics/**/*.js'
    },
    {
      name: 'Advanced',
      components: 'src/advanced/**/*.js'
    }
  ]
};

Темы

Стилизованные компоненты поддерживают создание тем из коробки. Но в руководстве по стилю тема не применяется, потому что ThemeProvider недоступен.

Самое простое решение - предоставить настраиваемую оболочку для всех живых примеров.

В styleguide.config.js файле добавьте эту запись:

module.exports = {
  ...
  styleguideComponents: {
    Wrapper: path.join(__dirname, 'src/ThemeProvider.js')
  },
};

Затем создайте свой ThemeProvide.js файл:

import React from 'react';
import { ThemeProvider } from 'styled-components';
import theme from './theme'
export default props => (
  <ThemeProvider theme={theme}>
    {props.children}
  </ThemeProvider>
);

Продолжение следует…

Я вернусь к теме «Гид по стилю жизни» в одной из следующих статей. Я покажу вам, как создать библиотеку многоразовых платформенно-независимых компонентов. Просто оставайся на связи.

Заключение

React Styleguidist - один из инструментов, который значительно упрощает вашу разработку. Установка и первоначальная настройка очень просты, а документация проста.

Вы можете настроить свое руководство по стилю разными способами. Например, я добавил собственные теги к каждому компоненту в моем руководстве по стилю. Это делает поиск и фильтрацию более мощными.

Вы можете работать в команде. В таком случае вы быстро увидите огромную выгоду от обмена своими компонентами и шаблонами проектирования с товарищами по команде в ясной и наглядной форме.

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

Ваш отзыв важен!

Если вам нравится моя история и вы хотели бы побуждать меня писать чаще, пожалуйста, хлопайте в ладоши, делитесь и комментируйте. Ваш интерес - лучшая мотивация поделиться моими мыслями.

Предыдущие истории