Включение и исключение файлов в вашем пакете 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
игнорируются. - Некоторые файлы всегда включаются, в то время как, с другой стороны, некоторые файлы всегда игнорируются, независимо от выбранного вами подхода.
Вот и все. Спасибо за чтение!