Как обновлять зависимости Gatsby при крупных обновлениях версий

Недавно я прошел через муки обновления своих стартеров Gatsby с Gatsby v2 до v4, что оказалось не так просто, как вам хотелось бы верить в интернете. С помощью нескольких добрых душ из Gatsby Discord я в конце концов справился с этим, и решил задокументировать процесс в этой статье.

Определение ожиданий

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

Застревание в аду зависимостей, когда npm install не работает из-за конфликтов версий зависимостей, но любая попытка разрешить их путем обновления или понижения пакетов просто переносит конфликт на другой набор зависимостей.
Запуск gatsby develop застревал в бесконечном цикле из-за ошибки в плагине Gatsby PostCSS, которая возникает только с определенными версиями Node. Плагин сообщества до сих пор не исправлен, и обходные пути включают либо удаление плагина, либо понижение версии Node, либо рефакторинг CSS таким образом, чтобы не вызывать ошибку.
Мой CSS сломался — не явным и очевидным образом, а скорее тонким способом, затрагивающим только строки, где CSS вложен, строка включает символ &, и некоторое значение в строке разрешается из переменной. Чтобы уточнить, мой CSS ломался только в тех строках, где выполнялись все три этих условия.
Другая тонкая поломка была связана с моими разместителями изображений, которые были неправильно выровнены из-за внутреннего изменения в gatsby-image. Это одна из тех вещей, которые случаются, когда вы сбиваетесь с проторенного пути. Внутренние компоненты Gatsby никогда не были гарантированно стабильны, так что можно сказать, что я сам на себя это навлек, полагаясь на внутренний API. Эта ошибка была особенно тонкой, потому что заполнители видны только во время загрузки изображения, поэтому при локальной разработке вы обычно их даже не замечаете. Однако реальный пользователь с медленным интернет-соединением увидит их, и перекос будет выглядеть довольно резким.

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

Как обновить

Следующие инструкции написаны для npm, но вы сможете следовать им, даже если используете yarn.

Общие советы:

Чтобы избежать ада зависимостей, вам следует обновлять все одновременно, а не по одному.
Ошибки Inscrutable часто решаются удалением .cache, node_modules и package-lock.json перед запуском npm install.
Не останавливайтесь на том моменте, когда сборка завершится успешно и автоматизированные тесты пройдут; вероятно, вам потребуется ручное тестирование, чтобы выявить все тонкие проблемы.

Пошаговая инструкция:

Перейдите на нужную версию Node (например, nvm use v16).
Убедитесь, что желаемая версия gatsby-cli установлена в данном окружении Node (например, npm install -g gatsby-cli@latest-v4).
Запустите ncu -u для изменения зависимостей package.json на самые новые версии (требуется npm-check-updates).
Вручную отредактируйте package.json, чтобы понизить версии пакетов, которые необходимо понизить для совместимости. Например, на момент написания этой статьи мне нужно было понизить версию React с v18 до v17, чтобы избежать ошибок гидратации (Gatsby не полностью поддерживает v18 на момент написания статьи).
Удалить .cache
Удалить node_modules
Удалить package-lock.json.
Молотите по npm install, пока он не запустится без ошибок. Вы можете ожидать появления множества ошибок, связанных с конфликтами версий в ваших зависимостях. Частым источником проблем являются необслуживаемые плагины, созданные сообществом. В некоторых случаях конфликты могут быть устранены путем понижения версии некоторых зависимостей, которые вы только что обновили. В других случаях вы можете удалить или заменить несовместимые плагины. В крайнем случае, вы можете попробовать npm install --legacy-peer-deps для принудительной установки, несмотря на конфликты версий. На практике необслуживаемые плагины часто работают с более новыми зависимостями.
Молотите по gatsby develop, пока он не будет работать без ошибок. Решение ошибок на этом шаге часто требует изменения зависимостей, в этом случае перейдите к шагу 5.
Когда вы запустили среду dev, пришло время запустить автоматизированные тесты и исправить все, что сломалось в соответствии с тестами.
После успешного прохождения тестов настало время вручную протестировать сайт в dev-среде и исправить все, что сломалось (неправильные CSS и т.д., которые не будут пойманы автоматическими тестами).
Кроме того, вы должны вручную проверить, что горячая перезагрузка не нарушена: Сначала внесите некоторые изменения в код. Затем проверьте, что изменения применяются в браузере без каких-либо действий внутри браузера. Затем попробуйте обновить сайт в браузере. Затем попробуйте перемещаться по разным страницам.
Когда ваша среда dev полностью работает, пришло время вручную протестировать производственную сборку (gatsby build && gatsby serve). Например, некоторые проблемы с маршрутизацией существуют только в производственной сборке.
После того, как все будет работать локально, самое время обновить конфигурацию CI, чтобы использовать ту же версию узла и gatsby-cli, которые вы используете локально. Это также подходящее время для обновления образа сборки и других артефактов, если это необходимо.
Обновите инструкции по настройке в README. (Я делаю это даже для своих личных проектов, потому что хочу знать, как я смогу запустить проект через 2 года после того, как забуду буквально все о его настройке. Хорошо написать в README такие вещи, как версия Node и версия gatsby-cli, потому что они не будут содержаться в вашем package.json).
Если у вас еще остались силы, вы можете продолжить работу над многочисленными предупреждениями npm и предупреждениями Gatsby, которые появились в результате обновлений.