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

В итоге я создал для этого стартер GatsbyJS и подумал, что расскажу, как легко было использовать как Stencil, так и Gatsby.

🖥 См. Сайт действующей документации 📓 Просмотрите исходный код на Github

✏️ Что такое StencilJS?

StencilJS - это набор инструментов для создания веб-компонентов. Это похоже на освещенный элемент от Google и команды Polymer, который предлагает утилиты и декораторы для простой загрузки веб-компонентов по стандарту W3C. Но StencilJS приносит больше, чем освещенный элемент, и обрабатывает все остальные части процесса: создание компонентов, автоматическое создание документации или даже модульное и E2E-тестирование. С помощью этого интерфейса командной строки вы можете мгновенно создавать стандартные веб-компоненты в комплекте с компонентом Typescript, CSS или SCSS и файлами тестирования E2E Typescript - и все это с помощью одной команды.

От кого-то, кому в прошлом приходилось настраивать новые проекты и иметь дело с долгим и трудоемким процессом настройки всего набора сборки и тестирования для приложения или библиотеки - я никогда не хочу делать это снова, если смогу помочь. Вот почему мне нравятся такие интерфейсы командной строки, как create-react-app, NextJS, NuxtJS, GatsbyJS, Gridsome, tsdx или create-react-library. Вы запускаете команду, и у вас есть готовый проект, будь то React, Vue или, в данном случае, веб-компоненты.

⚡️ Что такое GatsbyJS?

GatsbyJS - это генератор статических сайтов, оптимизированный для доставки PWA React, которые по умолчанию отображаются на стороне сервера и работают быстро. Вы заметите, что он используется в основном для проектов с большим количеством контента, которые используют его локальный API GraphQL для агрегирования различных API контента. Он обычно используется с Markdown или MDX, обычными синтаксисами записи, которые преобразуют такие символы, как ##, в элементы HTML <h2>.

Я выбрал Gatsby для этого проекта, особенно из-за того, насколько хорошо он работает с Markdown и JSON. Вы можете просто указать каталог с файлами Markdown и запрашивать их в приложении для создания страниц содержимого, печати навигационных меню и т. Д. А с помощью JSON вы можете импортировать его в GraphQL и запрашивать структурированные данные. А поскольку StencilJS автоматически выводит файлы Markdown и JSON для каждого компонента, это было идеальное сочетание.

🔧 Использование веб-компонентов в Gatsby

Чтобы использовать веб-компоненты в приложении, все, что вам нужно сделать, это импортировать комплект поставки в <head> вашего приложения (как и любой другой скрипт). Stencil по умолчанию создает комплект поставки как для ES6, так и для более ранней версии CommonJS. Пока вы импортируете оба в <head> своего приложения, в большинстве случаев все будет в порядке.

Гэтсби использует библиотеку под названием react-helmet для вставки содержимого в <head> DOM. Вы можете использовать компонент <Helmet> для вставки пакета вашего веб-компонента в <head> любой страницы (в идеале в корень):

Обычно я помещаю это в свой <Layout> компонент, который обертывает все страницы, так что каждая страница имеет доступ к компонентам. Вы можете найти его в документации по чисто веб-компонентам в layouts/documentation.js.

«Лучший» способ реализовать этот метод - использовать gatsby-browser.js и gatsby-ssr.js, чтобы обернуть все приложение нашими сценариями. Это гарантирует, что он действительно обертывает все приложение, а не там, где может начинаться <Layout> (на случай, если некоторые страницы не обернуты в него).

Версия ES6

Вы также можете использовать версию модуля ES6 (в данном случае из CDN) с резервным вариантом для IE11 / Edge:

Лучшая практическая версия React

Если вы предпочитаете решение, более ориентированное на React, вы также можете импортировать компоненты как модули NPM / ES6, если вы установили их как зависимости. Импортируйте модуль NPM туда, где он вам нужен (обычно в корень вашего приложения или вложенный маршрут / компонент), и запустите методы загрузки полифиллов и веб-компонентов:

Вы должны включить это в gatsby-browser.js и gatsby-ssr.js, чтобы применить его ко всему клиентскому приложению, а также когда Gatsby выполняет предварительную визуализацию для SSR. Вот пример этого в действии на CodeSandbox с использованием веб-компонентов Bulmil (Bulma CSS).

Обязательно ознакомьтесь с ** Руководствами по интеграции Stencil для примеров для каждой структуры , такой как Angular или Vue **, если вы заинтересованы в работе с ними.

Если вы попытаетесь импортировать свои веб-компоненты напрямую (без их компиляции и использования пакета распространения), вы столкнетесь с ошибкой сборки с Gatsby. Это связано с тем, что Gatsby генерирует статический HTML для своих компонентов React и для этого использует Node, который поддерживает только подмножество фактического веб-JS. Это означает, что Gatsby не может импортировать веб-компоненты , если они не предварительно скомпилированы и не включены в качестве клиентского тега <script> (или импорта ES6) в ваш HTML.

Если вам нужно использовать генератор статических сайтов с веб-компонентами, попробуйте найти тот, который основан на HTML, например 11ty. Я лично не пробовал, но, как сообщается, он лучше работает с веб-компонентами.

⚙️ Настройка Gatsby с помощью трафарета

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

Сначала мы устанавливаем несколько зависимостей, например gatsby-transformer-comment, который принимает файлы, которые мы загружаем в Gatsby, и анализирует любой Markdown:

Затем мы настраиваем gatsby-config.js для импорта нашего компонента Markdown из Stencil и запускаем анализатор Markdown (а также конвертируем блоки кода в PrismJS):

Эта конфигурация предполагает, что ваши веб-компоненты Stencil расположены в папке «над» папкой docs (или, точнее, документы Gatsby должны быть вложены в ваш корневой проект Stencil - stencil-web-components/docs/gatsby-config.js). Гэтсби берет документы Markdown компонента Stencil из настроенной папки и анализирует любой Markdown в HTML.

Все эти данные загружаются на локальный сервер GraphQL, где с данными работают «преобразователи». Наш Markdown анализируется в HTML плагином Remark. Но мы также можем запускать наши собственные сценарии для данных GraphQL. Нам нужны новые поля на нашем «узле» Markdown GraphQL для таких вещей, как ярлык страницы и категория / раздел. Я коснусь этого более подробно ниже, в разделе «Все уценки».

С помощью этих данных, которые мы запрашиваем, мы можем делать такие вещи, как отображать проанализированный HTML-код Markdown в нашем приложении или даже динамически создавать страницы на основе файлов.

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

И с этим у вас есть все, что вам в основном нужно. Гэтсби берет у Stencil Markdown и создает страницу для каждого. Гэтсби использует шаблон ./src/templates/component-docs.js для создания страниц, который, по сути, представляет собой просто оболочку React, которая запрашивает у GraphQL конкретный файл Markdown.

Для более подробного изучения, вы можете увидеть отличное руководство Гэтсби по созданию страниц с использованием Markdown здесь.

🚵‍♀️ UX и UI

Но я не хотел останавливаться на достигнутом. Мне нужно было создать меню боковой панели, в котором отображаются все компоненты и пользовательские страницы (с использованием конфигурации JSON). А что, если при синтаксическом анализе Markdown мы сможем заменить элементы HTML нашими веб-компонентами (например, заменить <button> на <pure-button)? И как кто-то на самом деле будет писать документы в Гэтсби?

Я взялся за каждый шаг за шагом 💪

Боковое меню

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

Мы запрашиваем компоненты в оболочке Layout, используя статические обработчики запросов GraphQL Gatsby, и передаем данные на нашу боковую панель:

Затем мы берем компоненты (через реквизиты) и просматриваем их на боковой панели вместе с пользовательскими страницами:

Мы перебираем каждый массив (компоненты и пользовательские страницы) и генерируем список ссылок. Здесь ничего особенного.

Замена Markdown HTML веб-компонентами

Допустим, вы хотите заменить <h1> элемента на <Header> компонент, когда пользователь пишет следующую Markdown: # Hello World. Вместо того, чтобы возвращать <h1> при разборе Markdown, вы можете заменить его любым нужным вам компонентом.

Обычно вы просто запрашиваете проанализированный HTML из конечной точки Markdown GraphQL, но в этом случае вы запрашиваете версию AST. Это позволяет вам менять местами элементы DOM в дереве с вашими собственными React или веб-компонентами.

Плагин Gatsby, обрабатывающий Markdown (gatsby-transformer-comment), рекомендует вам использовать библиотеку под названием rehype-react для изменения AST, предоставляемого парсером Gatsby Markdown:

Это немного «волшебство», поскольку все это происходит с использованием двух разных API-интерфейсов библиотек, но я не могу жаловаться на то, насколько легко это сделать (особенно если вы уже выполняли работу с AST раньше).

Вы можете увидеть пример этого в действии ниже, где я меняю <table> на свой <pure-table> компонент:

Markdown Everything

Чтобы упростить создание документации, я настраиваю Gatsby на получение любых файлов Markdown в src/pages/ каталоге стартера Gatsby. Это позволяет пользователям писать более длинные формы содержания и легко включать примеры кода. Альтернативой может быть запись содержимого внутри компонентов ReactJS, что требует специального решения для блоков кода и ограничивает автора записью на JSX (что может быть сложно для тех, кто не разбирается в причудах React).

Чтобы отличить документацию по компоненту от пользовательских страниц, я добавил новые поля в конечную точку Markdown GraphQL, которые включают «раздел» (компонент или страницу) и имя файла (для использования в заголовках компонентов):

Эта функция запускается, когда Гэтсби генерирует сервер GraphQL (gatsby-node.js), и добавляет к нему все новые поля, которые нам нужны.

Мы проверяем, является ли это файлом Markdown, а затем, если имя файла readme.md, мы предполагаем, что это автоматически сгенерированный файл документации компонента StencilJS. Используя этот раздел, мы также меняем ярлык страницы, поэтому, если это страница компонента, мы добавляем «компоненты», чтобы создать URL: components/pure-button/.

👩‍🎨 Интеграция вашей собственной системы дизайна трафаретов

Прелесть этого начального шаблона Gatsby заключается в том, что вы можете установить его вложенным внутри (или рядом) в проект веб-компонентов, и он автоматически создаст сайт документации для любых документов компонентов, которые создает Stencil.

Скопируйте стартер в репозиторий Stencil, установите зависимости документации (npm i или yarn), замените дистрибутив своим собственным (см. Ниже) и запустите yarn develop 🚀 Все готово!

Использование собственных веб-компонентов

В настоящее время начальный шаблон Gatsby ссылается на мою библиотеку веб-компонентов: чистые веб-компоненты.

Вы можете заменить его на свой собственный пакет веб-компонентов, отредактировав файл docs/src/layouts/documentation.js и изменив два сценария, заключенных в тег <Helmet>:

docs/src/layouts/documentation.js:

Вы заметите, что мы ссылаемся на относительный URL для пакета распространения. Предполагается, что вы скопировали папку Stencil dist в папку Gatsby static. Я включил пару сценариев NPM, чтобы синхронизировать ваши компоненты в package.json.

Если у вас есть возможность, вы должны использовать относительный модуль NPM (установка веб-компонентов в ваш проект Gatsby) или URL-адрес CDN.

Изменение каталога трафарета

Если вы предпочитаете хранить проекты отдельно, вы можете легко изменить конфигурацию плагина файловой системы (расположенный в docs/gatsby-config.js), чтобы он указывал на папку вашего проекта. В настоящее время он настроен на поиск папки src/components в родительской папке, но вы можете установить ее в любой относительный каталог.

docs/gatsby-config.js:

Когда сервер разработки Gatsby запускается, package.json также запускает другой сценарий, который удаляет сценарии компонентов из статической папки Gatsby и повторно копирует новый пакет компонентов из папки Stencil. Это позволяет вам использовать свои веб-компоненты без CDN и видеть, как выглядят документы с разрабатываемой версией компонентов.

Предполагается, что вы запускаете документы Gatsby, вложенные в проект Stencil. Но если вы измените папку компонентов в gatsby-config.js (как указано выше), вы должны обязательно изменить сценарий "components:copy" в docs/package.json, чтобы он указывал на правильный каталог.

Настройка боковой панели

Боковая панель состоит из 3 частей. Список настраиваемых страниц, автоматически созданный список компонентов и элементы списка, введенные вручную. Здесь вы можете добавлять собственные страницы, редактируя pages переменные.

docs/src/components/sidebar.js:

Вы также можете редактировать ручные ссылки в операторе return компонента боковой панели:

Если вы хотите изменить компоненты, отображаемые на боковой панели, вы можете отредактировать запрос GraphQL, который их возвращает. Он находится в docs/src/layouts/documentation.js и называется HeaderQuery. По умолчанию он будет захватывать все ваши компоненты, содержащие файлы Markdown, и создавать ссылки на боковой панели, но вы можете отфильтровать это по таким свойствам, как Markdown frontmatter с использованием фильтров GraphQL или ограничить его определенным числом.

Сборка и развертывание

Поскольку этот проект основан на копировании производственных пакетов из проекта Stencil (см. Выше: Изменение каталога Stencil), сложно создать эту тему с использованием такого процесса, как Netlify. Лучше всего использовать CDN (вместо сборок относительного распределения) или импортировать напрямую из NPM (и использовать Yarn Workspaces для локальной разработки). Вместо этого вы должны использовать пакеты JavaScript CDN или NPM (см. Выше: Использование собственных веб-компонентов).

Если вы используете зависимость CDN или NPM, отредактируйте package.json и удалите все сценарии копирования / синхронизации сценария сборки. Вы должны просто запустить gatsby build.

Если вы готовы пожертвовать рабочим процессом CI / CD, вы можете просто запустить yarn build локально и загрузить вывод HTML в Netlify. Вот так я начал работу с документами - немного более быстро и грязно.

🤔 Почему не тема Гэтсби?

Я пробовал использовать тему Гэтсби (а не «стартер») для этой документации. Вместо того, чтобы редактировать проект Gatsby напрямую с помощью «стартера», вы должны установить тему как зависимость и добавить ее в конфигурацию нового сайта Gatsby.

Проблема с процессом заключается в том, сколько настроек и настроек неизбежно потребуется пользователям в процессе. Это также потребовало переосмысления архитектуры проекта, сделав вещи более модульными и переопределяемыми (например, выделение пользовательских компонентов Markdown из файла), а также некоторые особенности тем по сравнению с начальными.

Чтобы добавить свою собственную библиотеку веб-компонентов Stencil, пользователю нужно будет создать 2 новых файла в своем собственном проекте для импорта своей библиотеки (gatsby-browser и gatsby-ssr) - помимо установки зависимости и добавления ее в config. Затем им придется отредактировать gatsby-config.js своего проекта, добавив некоторые необходимые свойства (например, страницы боковой панели). А для создания страниц они добавляли файлы Markdown в свой /src/pages/ каталог.

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

Вы можете увидеть, как продвигается тема Гэтсби здесь, на Github.

Автоматические документы веб-компонентов 🚀

Надеюсь, это поможет вам в процессе документирования вашего следующего проекта или дизайн-системы StencilJS! Документы часто могут быть самым утомительным процессом или дополнительной работой над всеми остальными вашими задачами, поэтому хорошо иметь в своем распоряжении любые инструменты, которые ускорят выполнение.

Если у вас есть какие-либо вопросы, не стесняйтесь задавать их в комментариях или напишите мне в Twitter. И если вы хотите внести свой вклад (или обнаружить ошибку 🐛👀), пожалуйста, создайте запрос на вытягивание или создайте проблему на Github 👍

использованная литература

Первоначально опубликовано на https://whoisryosuke.com 3 декабря 2019 г.