Протоколы

Таблица

Следующие протоколы могут быть использованы любым записям зависимостей, указанных в полях dependencies или devDependencies. Хотя они работают независимо от контекста, мы настоятельно рекомендуем использовать только диапазоны semver для опубликованных пакетов, поскольку они являются единственным общим протоколом, чья семантика чётко определена во всех менеджерах пакетов.

Детали

Exec

Этот протокол является экспериментальным и доступен только после установки опционального плагина.

Документация и использование находятся на GitHub: yarnpkg/berry/blob/master/packages/plugin-exec/README.md.

Git

Протокол Git, хотя и довольно старый, был существенно улучшен начиная с Yarn 2. В частности, стоит знать:

• Целевой репозиторий не будет использован как есть — он сначала будет упакован с использованием pack

• Вы можете явно запросить тэг, коммит, ветку или тэг semver, используя соответствующие ключевые слова (если ключевое слово отсутствует, Yarn будет искать первую подходящую вещь, как и в предыдущих версиях):

git@github.com:yarnpkg/berry.git#tag=@yarnpkg/cli/2.2.0
git@github.com:yarnpkg/berry.git#commit=a806c88
git@github.com:yarnpkg/berry.git#head=master

• Yarn будет использовать Yarn, npm или pnpm для упаковки репозитория, в зависимости от стиля репозитория (т.е. мы будем использовать Yarn, если есть yarn.lock, npm, если есть package-lock.json, или pnpm, если есть pnpm-lock.yaml)

• Рабочие области могут быть клонированы, если удалённый репозиторий использует Yarn или npm (npm@>=7.x должен быть установлен в системе); мы не можем поддерживать pnpm, потому что у него нет эквивалента для workspace команды. Просто укажите рабочую область по имени в вашем диапазоне (вы можете также дополнительно указать тэг):

git@github.com:yarnpkg/berry.git#workspace=@yarnpkg/shell&tag=@yarnpkg/shell/2.1.0

Patch

Протокол patch: предназначен для использования с yarn patch и yarn patch-commit. Он позволяет изменить исходные данные пакета, не разветвляя зависимость полностью. Предполагаемый рабочий процесс:

1. Найдите пакет, который вы хотите изменить (например, lodash@^1.0.0)
2. Запустите yarn patch lodash
3. Отредактируйте папку, созданную командой
4. После завершения запустите yarn patch-commit -s <path>
5. В вашем манифесте измените зависимость с ^1.0.0 на:

patch:lodash@^1.0.0#path/to/generated/file.patch

Обратите внимание, что если вы хотите обновить транзитивную зависимость (т.е. не вашу прямую), вы можете использовать поле resolutions.

Рабочая область

Протокол workspace: предназначен для использования с рабочими областями. Хотя Yarn автоматически выбирает разрешения рабочей области при совпадении, есть случаи, когда вы совершенно не хотите рисковать использованием пакета из удалённого репозитория, даже если версии не совпадают (например, если ваш проект не предназначен для публикации и вы просто хотите использовать рабочие области для лучшей компартментализации кода).

Наш текущий совет — использовать workspace:*, что практически всегда будет соответствовать вашим ожиданиям. Подробности об этом протоколе см. в документации по рабочим областям.

Часто задаваемые вопросы

Можно ли установить рабочую область проекта при использовании протокола Git?

Да! Yarn поддерживает рабочие области даже через зависимости Git, используя следующий синтаксис:

{
  "dependencies": {
    "my-pkg": "org/app#workspace=my-pkg"
  }
}

Вы даже можете комбинировать это с селекторами веток:

{
  "dependencies": {
    "my-pkg": "org/app#head=next&workspace=my-pkg"
  }
}

Примечание: Для работы этого подхода убедитесь, что каждая отдельная рабочая область может быть скомпилирована просто запустив yarn install && yarn pack в каждой отдельной рабочей области. В частности, избегайте сторонних скриптов выпуска, если они не используют yarn pack в качестве внутренней реализации.

Почему нельзя добавить зависимости через протокол Patch?

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

Чтобы добавить зависимости в пакет, либо разветвите его (и ссылайтесь на него через протокол Git, например), либо используйте механизм packageExtensions, который специально предназначен для добавления новых зависимостей времени выполнения в пакеты.

Почему протокол Link рекомендуется вместо псевдонимов для сопоставления путей?

Многие инструменты поддерживают функцию, обычно известную как «псевдонимы», которая позволяет сопоставить определённую директорию с именем пакета. Эта модель позволяет использовать обычные импорты пакетов (my-app/Toolbar) вместо потенциально сложных относительных путей (../../../Toolbar). Звучит потрясающе! Но почему мы не рекомендуем эту практику?

Как мы уже сказали, многие инструменты поддерживают эту функцию. Но секрет в том, что их реализации и настройки немного различаются. В зависимости от инструмента, это будет называться moduleNameMapper, resolve.alias, paths, или даже module.name_mapper. В зависимости от инструмента это будет регулярное выражение, специфический для данного инструмента язык или просто имя пакета. Все эти различия затрудняют синхронизацию настроек и повышают вероятность ошибок. Хуже того, это закроет доступ к инструментам, которые не поддерживают псевдонимы, поскольку они не будут знать, как обращаться с этими путями, о которых они ничего не знают.

И появляется протокол link:! Через него вы напрямую указываете пакетному менеджеру установить разрешение от данного имени к данному пути. Поскольку база знаний пакетного менеджера используется каждым пакетом в вашем проекте, добавление ссылки на зависимость достаточно, чтобы все ваши инструменты были осведомлены об этом новом соединении. Больше никаких дополнительных настроек 💫

{
  "dependencies": {
    "src": "link:./src"
  }
}

Совет: Yarn 2 реализует поддержку самоссылок, делая протокол link: ненужным в большинстве случаев. Любой файл, который является частью пакета, всегда сможет импортировать любой файл из своего пакета, используя имя пакета — даже из самого верхнего уровня проекта! Просто добавьте поле "name": "app" в свой файл package.json верхнего уровня, и вы сможете использовать import 'app/Toolbar' без дополнительных усилий.

Примечание: Вас может соблазнить использовать псевдоним для области без явного указания имени (т.е. "@app": "link:./src"). Не делайте этого. Эта модель неверна и не будет работать. Причина в том, что идентификаторы пакетов требуют имени пакета и необязательного имени области. В результате область без имени пакета — это синтаксическая ошибка. Предпочитайте использовать "app": "link:./src", что позволит вам по-прежнему использовать подкаталоги при необходимости (т.е. import 'app/toolbar/Icon').

Примечание: Прочитав этот раздел FAQ, вы можете подумать, что мы не рекомендуем использование псевдонимов вообще. Это не совсем верно. Хотя использование псевдонимов для сопоставления директорий — практика, которой мы не советуем следовать, они полезны в других контекстах. Например, использование псевдонима для отображения модуля fs в локальную модель вполне приемлемо.

В чем разница между Link и Portal?

Протокол link: предназначен для связи имени пакета с папкой на диске — любой папкой. Например, идеальное применение протокола link: — сопоставить вашу папку src с более понятным именем, которое затем можно использовать в ваших Node-приложениях без относительных путей (например, вы можете связать my-app с link:./src, чтобы вы могли вызывать require('my-app') из любого файла в вашем приложении).

Поскольку такие целевые папки обычно не содержат package.json, протокол link: даже не пытается их прочитать. Это может вызвать проблемы при попытке связать идентификатор с другим пакетом на диске (похоже на то, что делает yarn link), поскольку тогда транзитивные зависимости не разрешаются.

Для решения этой задачи новый протокол portal:, доступный в версии v2, открывает портал к любому пакету, расположенному на вашем диске. Поскольку порталы предназначены только для пакетов, они могут использовать информацию из файлов package.json, перечисленных в их целях, для правильного разрешения транзитивных зависимостей.