TL; DR - Storybooking - это процесс организации требований к проекту и компонентам (также известных как истории) таким образом, чтобы все аспекты взаимодействующих с пользователем частей могли быть доведены до сведения всех заинтересованных сторон. Эта статья знакомит читателя с модулем [tiny! *] Nuxt-stories, который призван сделать сбор историй относительно безболезненным и интересным для фреймворка Nuxt.

Отказ от ответственности: я являюсь автором модуля nuxt-stories. (* Я сделаю все возможное, чтобы он оставался крошечным ...)

Введение:

Правильное документирование и информирование о требованиях, возможно, является самой важной частью любого проекта. Тем не менее, во многих проектах кажется, что требования очень легко отделяются от реального написанного кода. Обычно требования записываются в отдельных статических местах, таких как электронные таблицы или слайды, а код пишется где-то еще. Это звучит как довольно простой способ организовать проблемы, но становится проблематичным, когда возникают несоответствия между одноразовыми письменными ожиданиями и постоянно меняющейся реальностью. Часто возникает необходимость повторять требования и код до тех пор, пока ожидания не оправдаются. Это особенно верно для веб-интерфейсов, где многие требования могут быть полностью субъективными (т. Е. Основанными на эстетике).

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

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

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

Хотя верно то, что компоненты можно разрабатывать непосредственно на страницах, разработчик вскоре обнаружит, что проектировать их изолированно от страниц будет намного проще. Иногда желательно увидеть, как будут выглядеть компоненты с фиктивными данными, а не с реальными данными, потому что… приложение еще не создано! Но даже если приложение находится в стадии разработки и сбор историй начался постфактум (ах!), Обычно нежелательно засорять папки страниц файлами «dummyData.json». Лучше оставить это, возможно, в папках историй (или фиктивных БД!) И в специальных ветках git «ux / flavour-123». Тогда для быстрого изменения представления достаточно просто изменить ветку git.

Storybooking в Nuxt:

Существует множество отличных решений для создания историй, многие из которых имеют отличные сообщества, функции и дополнения. Я очень уважаю эти решения! Они гораздо более опытны, чем модуль Nuxt, который я разработал неделю назад. Однако я решил создать модуль, потому что, когда дело дошло до Nuxt, я столкнулся с несколькими проблемами, когда хотел написать сборник рассказов и по-прежнему использовать некоторые «вещи Nuxt» и делать вещи «способом Nuxt».

В конце концов, потратив несколько часов на решение этой проблемы, я получил ~ большое осознание ~ того, что Nuxt уже предоставляет надежную архитектуру, которую можно просто расширить, добавив при желании сборники рассказов (т. Е. , в режиме разработки) и опускается, если не используется (в производстве). Это означает, что с помощью модуля включить Storybooking так же просто, как просто зарегистрировать модуль в конфигурации Nuxt. Давно исчезла необходимость выделить все воскресенье только для того, чтобы заставить работать сборник рассказов.

Установка:

  1. Модуль nuxt-stories зависит от: glob, pify и @ nuxt / utils. Они уже должны были быть установлены после запуска npx create-nuxt-app. Если это не так, установите их: npm i -D glob pify @nuxt/utils

2. Установите модуль: npm i -D nuxt-stories

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

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

В вашем nuxt.config.js файле просто укажите nuxt-stories как один из ваших buildModules. Он будет включен, только если ваша среда находится в режиме разработки ИЛИ если вы укажете forceBuild: true. Бывают случаи, когда вы хотите разместить приложение как статический сайт, чтобы вы также могли делиться историями. Однако обычно в процессе производства вы, вероятно, не захотите их упаковывать.

Использование: (просто!)

Как упоминалось ранее, при первой установке модуля должна быть создана папка .stories с примерами историй в ней. Эта папка обрабатывается точно так же, как папка ваших страниц, за исключением того, что в нее помещаются ваши истории. Маршруты создаются автоматически с помощью той же утилиты createRoutes(), которую Nuxt использует для создания маршрутов ваших страниц, поэтому вы можете структурировать свои истории аналогичным образом. Чтобы избежать конфликта с любыми реальными маршрутами, которые можно было бы назвать «рассказами», маршруты-истории будут начинаться с «.stories». Кроме того, вы можете найти полезным в рабочем процессе, чтобы файлы .stories располагались очень близко к папке компонентов в вашем рабочем дереве. Теперь в вашей среде IDE должно быть намного быстрее переключаться между двумя папками.

Чтобы увидеть свои истории, перейдите по адресу: https://[yourLocalHost]/.stories. Для нетерпеливых или тех, кто хочет испытать драйв, вы можете увидеть демо здесь:

Https://nuxt-stories.netlify.com

Как видите, это довольно просто и понятно, ничего особенного, но в этом суть. Рассказы можно полностью настроить по своему вкусу. Предпочитаете Vuetify Bootstrap? Не проблема! Ключевой вывод заключается в том, что для удобства разработчика необходимые маршруты автоматически генерируются по мере обновления историй. Сюжетные маршруты доступны в this.$router.options.routes. Если разработчик уже привык создавать страницы в папке «pages», это должно выглядеть очень знакомо!

Важные примечания и известные особенности:

  1. Маршруты историй нуждаются в «корне историй». Модуль использует первый найденный файл «.vue» в папке «.stories» в качестве корня историй. Итак, если у вас есть и index.vue, и файл root.vue в «.stories», будет использоваться index.vue, а не другой. Кажется, что это соглашение, что «index.vue» чаще используется в сообществе Nuxt.
  2. В каждой будущей установке nuxt-stories будет использоваться «аккуратное копирование», чтобы не перезаписывать все истории, над которыми вы работали. В случае сомнений зафиксируйте свои истории перед обновлением.
  3. Может быть, в какой-то момент вы захотите разместить свои истории на статическом веб-сайте, как это сделал я (чтобы вы могли легко поделиться ими с заинтересованными сторонами). Краткое объяснение: просмотрите или скопируйте мою ветку gh-pages, чтобы увидеть, как я все настроил, и просто отправьте ваш dist на свой хост (с разными хостами работать легче, чем с другими). Более подробное объяснение таково: выбор .stories в качестве папки историй - это и благословение, и проклятие. Файлы с . префикс обычно обрабатываются файловыми системами как скрытые. Если вы полностью контролируете сервер, у вас нет проблем с обслуживанием скрытых файлов. Однако другие платформы не будут включать скрытые файлы, даже если вы их отправили. Итак, чтобы избежать ошибки 404, вам придется переименовать папку .stories просто во что-то другое, например nuxtStories или stories, просто убедившись, что она не конфликтует с любыми другими реальными маршрутами историй, которые ваше настоящее приложение может использовать.
  4. ESLint также может игнорировать файлы или папки с префиксом «.». Если вы планируете включить «.stories» в качестве каталога для линтинга, вам нужно просто «отменить игнорирование» каталога в .eslintignore, добавив строку: !/.stories

Вывод:

Если повезет, если я все объяснил правильно, теперь в вашем приложении Nuxt должна быть включена функция Storybooking. В прошлом написание и поддержание требований всегда было пугающей скучной задачей, которой никто не хотел отвлекаться, но всегда, пожалуй, самой важной. Когда требования, которые вы пишете, состоят из функциональных компонентов, которые проверяются при сохранении и горячей перезагрузке на страницах вашего реального приложения, вы получите мгновенное удовлетворение от того, что ваше приложение уверенно движется к тому, что вы и ваши клиенты. хотите (и, надеюсь, в более короткие сроки, чем вы ожидали).