What actually gets included in your npm module?

August 01, 2016 0 Comments npm, nodejs, packages, publishing

Npm automatically includes some files. From the documentation (https://docs.npmjs.com/files/package.json#files) we can see the following files are always included regardless of settings:

  • package.json
  • README (and it's variants)
  • CHANGELOG (and it's variants)
  • LICENSE / LICENCE

There are also some files that always get ignored:

  • .git
  • CVS
  • .svn
  • .hg
  • .lock-wscript
  • .wafpickle-N
  • *.swp
  • .DS_Store
  • ._*
  • npm-debug.log

You can tell npm to include other files using the files array attribute in the package.json. This is an array of files to include in your project, you can also specify a folder name which will include all files in that folder.

You can exclude files by creating a .npmignore file. This is a list of files or folders that will not be included in your module build. In the absence of a .npmignore file, npm will pick up your .gitignore file and use it.

Sometimes you need to exclude a file from git but include it in your build, to get around this, as I've mentioned here, create an empty .npmignore file to ensure npm doesn't pick up your .gitignore file.

I've done some experimenting to see which config takes precedence over what.

Experiment time

Setup

Folder structure

ignore-test-1/  
|--index.js
|--test.js
|--package.json

.gitignore

index.js  
test.js  

.npmignore

index.js  
test.js  

files array

"files": ["index.js", "test.js"]

Test: files array + .npmignore

Result: package.json, index.js & test.js included

Winner: files array


Test: files array + .gitignore

Result: package.json, index.js & test.js included

Winner: files array


Test: just .npmignore

Result: package.json & index.js included


Test: just .gitignore

Result: package.json & index.js included


Conclusion The files array is the source that can't be overridden by .npmignore or .gitignore and the index.js gets included even if it's flagged to be ignored.

This conclusion is different from what I expected from reading the documentation so I did another experiment, this time with a more complicated folder structure, the results come to the same conclusion that the files array in the package.json is the source that cannot be overridden but if you forget to add to the files array, then the .npmignore and .gitignore files will kick in.