Практические способы создания потрясающих документов для вашей библиотеки пользовательского интерфейса.
Библиотеки компонентов - это де-факто современный способ повторного использования компонентов пользовательского интерфейса. Они помогают обеспечить согласованность пользовательского интерфейса в командах и стандартизировать разработку. При создании библиотеки компонентов React важно предоставить надлежащую документацию, чтобы люди могли принять и использовать компоненты.
Это может означать довольно много накладных расходов, поскольку вам придется настраивать и поддерживать как документацию, так и сам веб-сайт. В этом посте я собрал полезные способы и инструменты, чтобы упростить этот процесс, чтобы вы могли писать код и добавлять потрясающие документы.
Не стесняйтесь исследовать и пробовать эти инструменты или оставлять комментарии ниже и добавлять свои собственные. Помните: даже самый лучший компонент в мире ничего не стоит, если вы не можете его найти и использовать. Наслаждаться! :)
1. Bit.dev
Bit.dev - компонент-хаб для обмена повторно используемыми компонентами. Это позволяет вам постоянно собирать компоненты и повторно использовать их в проектах. Это быстрый, динамичный способ совместного использования компонентов в проектах.
Отличным побочным эффектом работы с Bit.dev является то, что вам не нужно поддерживать какие-либо дополнительные сайты документации для ваших компонентов. Вы получаете документы API, песочницы, ярлыки и многое другое прямо из коробки, чтобы сэкономить на накладных расходах.
Автоматически созданные документы API
Bit.dev использует проект с открытым исходным кодом Bit, чтобы стать вашим универсальным центром компонентов для повторного использования и синхронизации компонентов в проектах.
Когда вы пишете код, Bit обнаружит и извлечет документы из ваших JSDocs, MD-файлов и комментарии в самом коде. Затем он сгенерирует несколько типов документации, включая таблицу API, которая обновляется по мере обновления кода. Нет необходимости настраивать или поддерживать какие-либо дополнительные сайты с документацией, и он всегда в курсе последних версий ваших компонентов.
Пример "песочницы"
В Bit.dev каждый компонент визуализируется и визуализируется на редактируемой площадке, где вы можете сохранять и редактировать примеры. Это становится возможным, поскольку Bit изолирует каждый компонент и упаковывает его со всеми зависимостями в независимую среду разработки, чтобы вы могли визуализировать его независимо.
Результаты модульного тестирования
Поскольку Bit.dev запускает CI для каждого компонента, вы можете просматривать результаты модульного тестирования в виде документации на странице документации каждого компонента. Это полезно, поскольку тесты часто показывают, как именно работает компонент в различных крайних случаях.
Упорядочивайте и обнаруживайте компоненты
Компоненты Bit.dev организованы и помечены в зависимости от контекста и функциональности. Вы можете легко искать и фильтровать компоненты по имени, структуре, размеру, зависимостям и многому другому. Попробуйте здесь.
Установите или разветвите какие-либо компоненты
Каждый компонент можно установить прямо из реестра Bit.dev с помощью npm и yarn. Вы также можете bit import компонент для локального редактирования в любом проекте, сохранить новую версию и поделиться ею с коллекцией вашей команды.
2. Создайте собственный сайт статической документации.
Когда вы создаете библиотеку и не публикуете ее в таком хабе, как Bit.dev, вам в какой-то момент придется создать и поддерживать свой собственный сайт статической документации.
К счастью, экосистема с открытым исходным кодом предоставляет множество полезных инструментов, которые помогут выполнить эту работу. Среди популярных вы можете найти GitHub Pages, Gatsby, Docz, React-static и Docusaurus (не стесняйтесь добавлять другие предложения ниже, и я добавлю их в список). Эти инструменты автоматизируют и упрощают большую часть процесса с нуля до развертывания полной вики для ваших компонентов.
3. Сборник рассказов / гид по стилю
Отличным дополнением к любому сайту статической документации React является галерея визуальных примеров с такими инструментами, как или Styleguidist.
StoryBook и StyleGuidist - слишком замечательные инструменты, которые помогают разрабатывать компоненты изолированно, визуально визуализируя и документируя их.
StoryBook - это среда разработки компонентов пользовательского интерфейса. Он позволяет вам просматривать библиотеку компонентов, просматривать различные состояния каждого компонента, а также в интерактивном режиме разрабатывать и тестировать компоненты. При создании библиотеки StoryBook - это удобный способ визуализировать и документировать компоненты, а различные надстройки упрощают интеграцию с различными инструментами и рабочими процессами.
Поскольку поддерживается формат компонента-рассказа (CSF), рассказы, написанные в этом формате, могут отображаться во многих местах, в том числе в вашей коллекции Bit.dev.
StyleGuidist - это среда разработки изолированных компонентов React с живым руководством по стилю. Он предоставляет горячую перезагрузку сервера разработки и живое руководство по стилю, в котором перечислены компоненты propTypes и показаны редактируемые примеры использования на основе файлов .md. Он поддерживает ES6, Flow и TypeScript и работает с приложением Create React из коробки. Автоматически сгенерированные документы по использованию могут помочь Styleguidist функционировать как портал документации для различных компонентов вашей команды.
- Также ознакомьтесь с UI Zoo Ноамом Эльбоймом.
4. Codesandbox / Stackblitz / Codepen
Компонентные площадки - это отличный способ поиграть с компонентами и узнать, как они работают. Когда вы можете объединить их как часть вашей документации (или как часть вашего рабочего процесса совместно используемых компонентов), игровые площадки помогут вам быстро изучить, как работает код, и решить, хотите ли вы использовать компонент.
Codesandbox - это онлайн-редактор для быстрого создания небольших проектов, таких как компоненты, и игры с ними. Создав что-то интересное, вы можете показать это другим, просто поделившись URL-адресом. CodeSandbox имеет предварительный просмотр в реальном времени, чтобы показать результат кода, пока вы печатаете, и имеет встроенные расширения для интеграции в ваши различные инструменты и рабочий процесс разработки.
Stackblitz - это онлайн-среда разработки для веб-приложений на базе Visual Studio Code. Как и Codesnadbox, StackBlitz - это онлайн-среда IDE, в которой вы можете создавать проекты Angular и React, которыми можно делиться через URL-ссылку. Как и Codesandbox, он автоматически заботится об установке зависимостей, компиляции, объединении и горячей перезагрузке по мере ввода. Взглянем.
→ Найдите еще игровые площадки для React:
- Смотрите также: React-Cosmos | Реагировать-жить
