Что хорошего в компонентах, если никто не понимает, как их найти и использовать?
React рекомендует вам создавать модульные приложения с компонентами. Модульность дает всевозможные преимущества, включая улучшенную возможность повторного использования. Но когда вы стремитесь поделиться и повторно использовать компонент, вам лучше убедиться, что его легко обнаружить, понять и использовать. Вам необходимо задокументировать компоненты.
Сегодня современные инструменты могут помочь автоматизировать некоторые рабочие процессы документирования и превратить использование документации по компонентам в богатый, визуальный и даже интерактивный опыт. Некоторые инструменты даже объединяют такие документы как неотъемлемую часть самого рабочего процесса обмена компонентами.
Чтобы вы могли составить красивую документацию по компонентам, не прилагая слишком много усилий, я собрал некоторые из лучших и самых популярных инструментов для документирования компонентов React. Не стесняйтесь комментировать и добавлять свои собственные идеи и инструменты.
1. Бит
Платформа для общих компонентов.
Bit больше, чем просто инструмент для документирования компонентов. Это инструмент с открытым исходным кодом, который позволяет инкапсулировать компоненты со всеми их файлами и зависимостями и сразу же запускать их в различных приложениях.
Платформа bit.dev позволяет вам совместно использовать и совместно работать над компонентами ваших приложений. Все ваши общие компоненты становятся доступными для вашей команды, чтобы они могли их находить и использовать в своих проектах, а также легко делиться своими собственными компонентами.
Компоненты, которыми вы делитесь с bit.dev, становятся доступными для обнаружения в центре общих компонентов вашей команды. Вы можете искать компоненты по контексту, размеру пакета или даже по зависимостям. Вы можете быстро просматривать результаты на основе визуальных снимков фактически визуализированных компонентов и выбирать их глазами.
→ Изучить компоненты на bit.dev
Когда вы зайдете на одну из веб-страниц своего компонента, вы обнаружите, что Bit представляет компонент на игровой площадке, так что вы можете поиграть с ним, прежде чем использовать его в своем приложении. Если у вас есть JSDocs или файл .md как часть кода, Bit также проанализирует и представит эти документы. Если компоненты включают файлы модульного теста, Bit запустит их изолированно и представит результаты как часть документации для каждого компонента.
Когда вы найдете компонент, который вам нравится использовать, просто используйте NPM или Yarn для его установки. Вы даже можете использовать Bit для разработки и обновления компонентов непосредственно из любого приложения-потребителя, чтобы ваша команда могла сотрудничать и строить вместе.
При совместном использовании компонентов через Bit вам не нужно создавать больше репозиториев или инструментов, не нужно реорганизовывать или изменять код, а тот же хаб, где вы делитесь компонентами, - это то место, где они становятся документированными и обнаруживаемыми, в значительной степени из коробки .
Начать:
2. StoryBook и Styleguidist
StoryBook и StyleGuidist - слишком замечательные проекты, которые помогают разрабатывать компоненты изолированно, визуально визуализируя и документируя их.
StoryBook - это среда разработки компонентов пользовательского интерфейса. Он позволяет просматривать библиотеку компонентов, просматривать различные состояния каждого компонента, а также в интерактивном режиме разрабатывать и тестировать компоненты. При создании библиотеки StoryBook - это удобный способ визуализировать и документировать компоненты, а различные надстройки упрощают интеграцию с различными инструментами и рабочими процессами. Вы даже можете повторно использовать истории в модульных тестах для подтверждения тонкой функциональности.
StyleGuidist - это среда разработки изолированных компонентов React с живым руководством по стилю. Он предоставляет горячую перезагрузку сервера разработки и живое руководство по стилю, в котором перечислены компоненты propTypes и показаны редактируемые примеры использования на основе файлов .md. Он поддерживает ES6, Flow и TypeScript и работает с приложением Create React из коробки. Автоматически сгенерированные документы по использованию могут помочь Styleguidist функционировать как портал документации для различных компонентов вашей команды.
- Также ознакомьтесь с UI Zoo Ноамом Эльбоймом.
3. Codesandbox, Stackblitz и друзья
Компонентные площадки - это отличный способ поиграть с компонентами и узнать, как они работают. Когда вы можете объединить их как часть вашей документации (или как часть вашего рабочего процесса совместно используемых компонентов), игровые площадки помогут вам быстро изучить, как работает код, и решить, хотите ли вы использовать компонент.
Codesandbox - это онлайн-редактор для быстрого создания небольших проектов, таких как компоненты, и игры с ними. Создав что-то интересное, вы можете показать это другим, просто поделившись URL-адресом. CodeSandbox имеет предварительный просмотр в реальном времени, чтобы показать результат кода, пока вы печатаете, и имеет встроенные расширения для интеграции в ваши различные инструменты и рабочий процесс разработки.
Stackblitz - это онлайн-среда разработки для веб-приложений на базе Visual Studio Code. Как и Codesnadbox, StackBlitz - это онлайн-среда IDE, в которой вы можете создавать проекты Angular и React, которыми можно делиться через URL-ссылку. Как и Codesandbox, он автоматически заботится об установке зависимостей, компиляции, объединении и горячей перезагрузке по мере ввода. Взглянем.
→ Найдите еще игровые площадки для React:
- Смотрите также: React-Cosmos | Реагировать-жить
4. Докз
Docz упрощает создание веб-сайтов с документацией на Gtabsy для вашего кода. Он основан на MDX (Markdown + JSX), чтобы использовать уценку для документации по компонентам. По сути, вы можете написать файл .mdx в любом месте вашего проекта, и Docz упростит процесс превращения его в портал документации вашего собственного дизайна, развернутый в Netlify. Полезно, правда?
5. Документы MDX
MDX-docs позволяет документировать и разрабатывать компоненты React с помощью MDX и Next.js. Вы можете смешивать уценку со встроенным JSX для рендеринга компонентов React. Напишите уценку, как обычно, и используйте синтаксис импорта ES для использования пользовательских компонентов в вашем документе. Встроенные компоненты визуализируют защищенные JSX блоки кода как предварительные просмотры в реальном времени с редактируемым кодом на основе react-live.
Взглянем.
6. React Docgen
React DocGen - это интерфейс командной строки и набор инструментов для извлечения информации из файлов компонентов React для создания документации. Он использует ast-типы и @ babel / parser для синтаксического анализа исходного кода в AST и предоставляет методы для обработки этого AST для извлечения желаемой информации. Выходное / возвращаемое значение - это объект JSON blob / JavaScript. Он обеспечивает реализацию по умолчанию для компонентов React, определенных через React.createClass, определения классов ES2015 или функции (компоненты без состояния). Функциональный и мощный.
- Также см. Component-docs:
