Как запустить библиотеку компонентов React с помощью Storybook и Create-React-App

React — один из ведущих фреймворков для фронтенд-разработки с использованием JavaScript. Это естественный подход, основанный на компонентах, когда вы собираете свое приложение из повторно используемых частей автономной функциональности.

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

В этой статье мы соберем простой набор компонентов React с помощью Storybook, а затем упакуем их с помощью Babel. Storybook предоставляет удобный способ проверки компонентов во время и после их разработки. Это интерфейс для просмотра вашей библиотеки, экспериментов с включенными компонентами и просмотра документации.

В этой статье мы не будем подробно рассматривать какую-либо отдельную технологию: вместо этого это обзорное руководство о том, как разрабатывать, упаковывать и визуализировать компоненты с использованием комбинации React, Storybook и Create-React-App.

Что такое сборник рассказов?

Storybook — это просто набор инструментов для разработки и рендеринга компонентов изолированно, вне контекста, в котором они появляются в вашем приложении. Он предоставляет механизм для создания компонентов, документирования их свойств и предоставления интерактивных примеров визуализации в пользовательском веб-интерфейсе. Storybook не зависит от фреймворка: вы можете использовать его с Angular, Vue, Ember, Svelte и другими, помимо React.

Компоненты создаются путем написания вашего обычного кода React, а затем добавления второго сопутствующего файла, который описывает «истории» для этого компонента. Ваш фактический компонент не изменился; Storybook получает всю необходимую информацию из прилагаемого файла .stories.js. Storybook автоматически обнаруживает эти файлы и использует их содержимое для создания записей в веб-интерфейсе вашей библиотеки.

Мы увидим модель в действии позже, когда приступим к написанию компонентов. Сначала вам нужно создать новый проект React и добавить в него Storybook.

Инициализация вашего проекта React

Мы собираемся использовать популярный набор инструментов create-react-app (CRA) для инициализации проекта. Это дает вам все необходимое для создания компонентов React. Он также полностью поддерживается Storybook.

Откройте свой терминал и введите эту команду, чтобы создать свою библиотеку:

npx create-react-app my-components

Нажмите y, чтобы подтвердить установку create-react-app, если вы никогда раньше не использовали этот инструмент. Процесс установки может занять пару минут. Как только это будет сделано, перейдите в новый каталог my-components. CRA добавит зависимости React в ваш package.json и создаст базовое приложение React в каталогах public и src.

CRA предполагает, что вы разрабатываете кодовую базу, которая будет доставлена прямо в браузер. Поскольку на самом деле мы создаем библиотеку, которая не будет работать как отдельное приложение, вы можете безопасно удалить каталоги по умолчанию public и src, если хотите.

Добавление сборника рассказов

Добавить Storybook в существующий проект CRA очень просто. Выполнение этой команды даст вам все, что вам нужно:

npx sb init

Будьте готовы снова подождать пару минут, пока пакеты Storybook добавятся в ваш проект. Программа установки создаст новые каталоги .storybook и stories. Последний содержит набор компонентов-примеров. Удалите этот каталог сейчас, так как мы не будем его использовать.

Файлы в .storybook настраивают ваш сервер Storybook. main.js содержит глобальные настройки, такие как шаблоны имен файлов для поиска историй. preview.js управляет тем, как истории отображаются в веб-интерфейсе Storybook. Ссылки на оба этих файла доступны в документации Storybook; на данный момент требуется только одно изменение.

По умолчанию Storybook ищет истории в вашем каталоге stories. Это не имеет особого смысла для проекта, который представляет собой исключительно библиотеку компонентов. Мы поместим наши компоненты с их историями прямо в каталог src, используя формат src/ComponentName.js и src/ComponentName.stories.js. Измените поле stories в файле .storybook/main.js, чтобы оно ссылалось на каталог src вместо stories:

module.exports = {
    "stories": [
        "../src/**/*.stories.@(js|jsx|ts|tsx)"
    ],
    // ...
}

Этот фрагмент означает, что Storybook будет обнаруживать истории в файлах в каталоге src, которые имеют суффикс .stories.js; Также поддерживаются варианты .jsx (React JSX), .ts и .tsx (TypeScript). Если вы не хотите использовать эту файловую структуру, найдите время, чтобы настроить соответствующие шаблоны Storybook по своему вкусу.

Написание ваших компонентов

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

import PropTypes from "prop-types";
 
const styles = {
    background: "#fff",
    border: "0.2rem solid #0099ff",
    color: "#0099ff",
    letterSpacing: "0.1em",
    fontWeight: "bold",
    padding: "1em",
    textTransform: "uppercase"
};
 
const Button = ({disabled, label, onClick}) => (
    <button disabled={(disabled ? "true" : "")} onClick={onClick} style={styles}>
        {label}
    </button>
);
 
Button.propTypes = {
    disabled: PropTypes.bool,
    label: PropTypes.label,
    onClick: PropTypes.func
};
 
Button.defaultProps = {
    disabled: false
};
 
export default Button;

Затем создайте файл истории компонента. Вот как Storybook найдет компонент и поймет его конфигурацию.

import Button from "./Button.js";
 
export default {
    title: "Button",
    component: Button,
    args: {
        label: "Demo Button"
    }
};
 
const Template = args => <Button {...args} />;
 
const Standard = Template.bind({});
 
const Disabled = Template.bind({});
Disabled.args = {disabled: true, label: "Disabled Button"};
 
export {Standard, Disabled};

Экспорт модуля default предоставляет метаданные для Storybook. Это должен быть объект, включающий свойства title и component. title используется для обозначения вашего компонента в пользовательском интерфейсе Storybook; component — это функция компонента или класс, который вы предоставляете.

args в Storybook эквивалентны props в React. Свойство args экспорта по умолчанию эффективно устанавливает значения реквизита по умолчанию для применения к экземплярам компонентов, визуализируемым Storybook. Здесь кнопки получают метку Demo Button, если свойство не изменилось позже.

Именованные экспорты вашего модуля определяют фактические экземпляры компонентов, которые будут представлены в вашем сборнике рассказов. Требуется хотя бы один. Здесь создаются две кнопки: кнопка Standard в состоянии по умолчанию и кнопка Disabled, которая устанавливает свойство disabled в true..

Теперь запустите сервер разработки Storybook:

npm run storybook

Посетите localhost:6006 в браузере, чтобы просмотреть библиотеку компонентов. Вы должны увидеть компонент Button на боковой панели с двумя именованными вариантами истории. Щелчок по одной из историй покажет вам состояние рендеринга компонента.

Вкладка «Элементы управления» под холстом рендеринга позволяет динамически изменять значения реквизита в пользовательском интерфейсе Storybook. Это позволяет быстро и легко экспериментировать с различными комбинациями реквизита, когда вы открываете компоненты, созданные другими. Существует несколько различных способов, с помощью которых Storybook может найти элементы управления; в данном случае они поступают из propTypes, назначенного компоненту Button.

Storybook автоматически обрабатывает «действия» компонентов, такие как свойство onClick нашей кнопки. В реальном приложении вы должны указать функцию для этого реквизита, которая будет вызываться при нажатии кнопки. В Storybook нажатие кнопки регистрирует событие на вкладке «Действия» под холстом. Это включает в себя имя вызываемого реквизита и параметры, которые были бы переданы его обратному вызову.

Здание с Бабелем

Теперь мы написали простой компонент React, создали для него историю и использовали Storybook, чтобы проверить, как компонент отображается так, как мы ожидали. Следующим шагом будет сборка вашей библиотеки компонентов и ее упаковка с помощью npm, готовая к включению в ваше следующее приложение.

К сожалению, вы не можете просто npm опубликовать необработанные файлы JavaScript. Приложение Create React не транспилирует JSX в пакеты в папке node_modules вашего приложения, поэтому вы получите ошибку сборки при попытке запустить проект с вашими компонентами. Вам необходимо транспилировать библиотеку компонентов перед публикацией с помощью такого инструмента, как Babel.

Начните с добавления файла src/index.js, который будет экспортировать публичный API вашего модуля:

import Button from "./Button.js";
export {Button};

Это позволит пользователям вашего пакета получить доступ к модулю Button, написав:

import {Button} from "@example/example-components";

Это дает вам свободу изменять пути к файлам в будущем, не затрагивая пользователей вашей библиотеки. Общедоступный API вашего пакета теперь определяется экспортом index.js.

Затем добавьте Babel в свой проект с помощью следующей команды:

npm install --save-dev 
    @babel/cli 
    @babel/plugin-transform-react-jsx 
    @babel/preset-env 
    @babel/preset-react

Создайте файл .babelrc в корне вашего проекта со следующим содержимым:

{
    "presets": [
        "@babel/preset-env",
        "@babel/preset-react"
    ],
    "plugins": [
        [
            "@babel/plugin-transform-react-jsx",
            {
                "runtime": "automatic"
            }
        ]
    ]
}

Эта конфигурация Babel активирует поддержку React с новым преобразованием JSX. Это означает, что вам не нужно импортировать React из \react\; вверху каждого файла, использующего JSX.

Наконец, добавьте следующие строки в раздел scripts вашего файла package.json:

"scripts": {
    "prepare": "npm run dist",
    "dist": "rm -rf dist/* && babel src/ --out-dir dist --copy-files --no-copy-ignored --ignore src/**/*.stories.js"
}

Сценарий prepare автоматически выполняется npm до того, как ваш пакет будет опубликован в реестре. Он используется здесь для компиляции ваших компонентов каждый раз, когда вы загружаете новую версию.

Теперь вы можете запустить npm run dist, чтобы создать готовую к распространению сборку вашей библиотеки. Выходные файлы будут помещены в каталог dist. Рекомендуется добавить это в ваш файл .gitignore.

Осталось сделать два изменения. Сначала нужно указать npm публиковать только собранные файлы в вашем каталоге dist. Это контролируется через поле files в вашем package.json. Вторая настройка заключается в том, чтобы ссылаться на скомпилированную версию вашего index.js в качестве точки входа пакета, используя поле main:

{
    "files": [
        "dist"      
    ],
    "main": "dist/index.js"
}

Готово! Теперь вы можете npm опубликовать свой пакет и npm установить его в одном из ваших приложений. Загруженный пакет будет содержать только скомпилированный код, очищенный от JSX и готовый к использованию в вашем проекте. Попробуйте это на минимальном примере в новом приложении CRA:

import {Button} from "@example/example-components";
 
export default () => <Button />;

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

Заключение

Требуется небольшая предварительная работа, чтобы собрать библиотеку компонентов React. Вам нужно написать сами компоненты, найти способ проверить их во время разработки, а затем предложить пользователям механизм обнаружения, опробования и изучения доступных компонентов. Когда придет время опубликовать ваш пакет, вам нужно настроить транспиляцию и настроить npm для обслуживания ваших скомпилированных файлов.

Storybook решает первую из этих проблем, предоставляя специальный интерфейс для рендеринга и экспериментов с компонентами. Его легко интегрировать с приложением Create React, оно не требует внесения изменений в ваши фактические компоненты и прекрасно сочетается с концепциями React.

Вы можете решить проблемы с распространением, используя Babel для создания перенесенных сборок ваших компонентов перед их публикацией. Поля main и files в npm помогают контролировать, что упаковывается, и предоставляют пользователям удобный общедоступный API. После того, как вы закончите настройку, вы можете опубликовать свой пакет в реестре npm или на собственном частном сервере, а затем импортировать готовые компоненты туда, где они вам нужны.

---

---