Включение и исключение файлов в вашем пакете npm

Введение

После публикации статьи о разработке и публикации пакета npm с использованием TypeScript я получил предложение в Твиттере создать .npmignore в дополнение к .gitignore, иначе ваш dist не будет включен (если dist находится в .gitignore ). Хотя это верно (вам не нужно добавлять файл .npmignore, если вы используете поле files в файле package.json), учитывая, что все три подхода влияют на то, что get включено в ваш пакет npm, я написал эту статью, чтобы попробовать и демистифицировать процесс.

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

Задний план

Мы продолжим использовать этот демонстрационный пакет npm для этой статьи. Исходный код этого пакета можно найти на GitHub. В этой статье предполагается, что папка dist добавлена в файл .gitignore.

Сценарий 1: Использование файлов для включения того, что вы хотите

Чтобы явно указать, какие файлы вы хотите включить в пакет npm, вы можете использовать поле файлов в файле package.json. Вы можете напрямую указать имя файла или папки или использовать шаблон глобуса. Фрагмент кода ниже упаковывает папку dist и все файлы внутри папки dist, файлы LICENSE и файлы README.md.

Фактически, файлы LICENSE, package.json и README.md (среди нескольких других файлов) включены по умолчанию, поэтому вы можете не включать их в поле файлов, если хотите. Вы можете запустить команду npm publish --dry-run, чтобы подтвердить, какие файлы будут упакованы.

В этом сценарии поле файлов в файле package.json имеет приоритет над файлом .gitignore. Вот почему, несмотря на то, что папка dist находится в файле .gitignore, она включена в пакет npm, потому что мы явно включили ее в поле файлов.

Сценарий 2: не использовать файлы

Если вы решите удалить поле files из файла package.json и попробуете запустить команду npm publish --dry-run, чтобы увидеть, какие файлы будут упакованы, вы будете удивлены, обнаружив, что будут включены почти все остальные файлы, не являющиеся частью файла .gitignore. Это происходит потому, что если вы опустите поле файлов, для поля файлов будет установлено значение по умолчанию [“*”], что означает, что оно будет включать все файлы.

Поэтому в этом сценарии файл .gitignore действует только как список исключений, и все, что не является частью этого файла, будет включено в пакет npm.

Сценарий 3: Использование файла .npmignore.

Мы определенно не хотим, чтобы все остальные файлы и папки были включены в пакет npm по разным причинам:

  • Это увеличивает размер пакета npm.
  • Мы не хотим, чтобы файлы разработки распространялись.

Чтобы смягчить это, мы можем создать новый файл с именем .npmignore и перечислить файлы и папки, которые мы не хотим упаковывать. Пример может выглядеть примерно так, как приведенный ниже фрагмент кода.

Теперь, если мы снова запустим команду npm publish --dry-run, мы обнаружим, что наш вывод выглядит так же, как когда мы использовали поле файлов в файле package.json.

Таким образом, в этом сценарии, поскольку файл .npmignore найден, содержимое файла .gitignore игнорируется.

Включения и исключения по умолчанию

Согласно документации npm, определенные файлы включаются всегда, независимо от настроек:

  • package.json
  • README
  • CHANGES / CHANGELOG / HISTORY
  • LICENSE / LICENCE
  • NOTICE
  • Файл в «основном» поле

README, CHANGES, LICENSE и NOTICE могут иметь любой регистр и расширение.

И наоборот, некоторые файлы всегда игнорируются:

  • .git
  • CVS
  • .svn
  • .hg
  • .lock-wscript
  • .wafpickle-N
  • .DS_Store
  • npm-debug.log
  • .npmrc
  • node_modules
  • config.gypi
  • package-lock.json (вместо этого используйте термоусадочную пленку)
  • Все файлы, содержащие символ * (несовместимы с Windows)

Вывод

В итоге -

  • Я бы рекомендовал использовать раздел файлов в файле package.json вместо добавления файла .npmignore. Лучше явно указать, что вы хотите, вместо того, чтобы перечислять все, что вы не хотите включать — это требует больше усилий и есть вероятность, что вы забудете добавить новый файл в список исключений.
  • Файлы, включенные в поле файлов файла package.json, нельзя исключить с помощью .npmignore или .gitignore. На самом деле файлы .npmignore и .gitignore игнорируются.
  • Некоторые файлы всегда включаются, в то время как, с другой стороны, некоторые файлы всегда игнорируются, независимо от выбранного вами подхода.

Вот и все. Спасибо за чтение!